opencastle 0.32.5 → 0.32.6

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

@@ -3,134 +3,64 @@ name: testing-workflow
 description: "Comprehensive testing workflow including test planning, unit/integration/E2E testing patterns, coverage requirements, and common testing mistakes. Use when writing tests, planning test strategies, or validating feature completeness."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Testing Workflow
 
-## Core Principles
-
-- Test implementations thoroughly before claiming completion.
-- Every feature must be validated through comprehensive testing covering happy paths, edge cases, error conditions, and user interactions.
-- **Mandatory**: Every feature implementation must be tested in the browser using the project's E2E testing tool (resolved via the **e2e-testing** capability slot) before marking as complete.
+## Core Rules
 
-## E2E Testing Context Management
+- Validate every feature: happy paths, edge cases, error conditions, interactions.
+- **Mandatory**: Test in browser via the **e2e-testing** capability slot before marking complete.
 
-**Problem:** Comprehensive E2E tests with Chrome MCP accumulate context that can exceed AI context limits (413 errors).
+## E2E Context Limits
 
-**Rules:**
-1. **ONE suite per session** — never run all suites in one conversation.
-2. **MAX 3 screenshots** per session.
-3. **Use `evaluate_script()` over `take_snapshot()`** — returns less data.
-4. **Reload between major test flows** to clear state.
-5. **Log results separately** — append to `.opencastle/logs/e2e-results.md`.
+| Rule | Detail |
+|------|--------|
+| One suite per session | Never run all suites in one conversation |
+| Max 3 screenshots | Per session |
+| `evaluate_script()` over `take_snapshot()` | Returns less data |
+| Reload between flows | Clears state |
+| Log results | Append to `.opencastle/logs/e2e-results.md` |
 
-### Suite Files
-
-See `.opencastle/project.instructions.md` for the full list of E2E test suite files.
+Suite files: see `.opencastle/project.instructions.md`.
 
 ## Pre-Implementation Test Plan
 
-Before implementing any feature, create a plan covering:
-
-### 1. Initial State Tests
-- Page loads with default values.
-- Components render in expected initial state.
-
-### 2. User Interaction Tests
-- Buttons trigger expected actions.
-- Dropdowns respond to selection.
-- Filters update URL params and trigger data refetch.
-- Forms accept and validate input.
-
-### 3. State Transition Tests
-- Changing filter values produces different results.
-- Data updates on user interaction.
-- UI reflects backend state changes.
-- Loading states appear during async operations.
-
-### 4. Edge Case Tests
-- Empty results.
-- Maximum/minimum boundaries.
-- Invalid input handling.
-- Network errors and timeouts.
-
-### 5. Integration Tests
-- Component interactions work correctly.
-- Data flows from server to UI properly.
-- URL parameters sync with component state.
-- Server-side vs client-side filtering works.
-
-### 6. Responsive Breakpoint Tests (MANDATORY for UI changes)
-
-**Every UI feature must be tested at all responsive breakpoints** defined in your project's testing config. Most layout bugs only surface at smaller viewports.
-
-> **Detailed breakpoint definitions, resize commands, and per-breakpoint checklists:** See the **browser-testing** skill. The **validation-gates** skill (Gate 3) defines the mandatory testing protocol.
-
-**Anti-pattern:** Testing only at desktop (or only at the default browser width) and assuming responsive classes work. CSS utility classes can be incorrect — always verify visually at every breakpoint.
+| Category | What to cover |
+|----------|---------------|
+| Initial state | Page loads with defaults; components in expected state |
+| User interactions | Buttons, dropdowns, filters (URL params + refetch), form validation |
+| State transitions | Filter changes produce different results; loading states; backend sync |
+| Edge cases | Empty results, min/max boundaries, invalid input, network errors |
+| Integration | Data flow server→UI, URL params↔state, server vs client filtering |
+| Responsive (MANDATORY for UI) | All breakpoints per **browser-testing** skill / **validation-gates** Gate 3 |
 
 ## Coverage Requirements
 
-### Unit Tests
-- **Minimum 95% coverage** for all new code.
-- All exported functions, React components, custom hooks.
-- Edge cases and error conditions. Input validation.
+| Layer | Minimum |
+|-------|---------|
+| Unit (functions, components, hooks) | 95% |
+| Integration (boundaries, URL sync) | All boundaries |
+| E2E (journeys, interactions, errors) | All critical paths |
 
-### Integration Tests
-- Component integration, data flow, state updates across boundaries.
-- URL synchronization.
-
-### E2E Tests (Browser Automation)
-- Complete user journeys. All interactive elements.
-- State transitions. Error handling. Performance.
-
-## Testing Anti-Patterns
+## Anti-Patterns
 
 | Anti-Pattern | Correct Approach |
 |---|---|
-| Testing only initial page load | Test filter changes, interactions, different results |
-| Assuming filters work because they render | Verify each filter option changes results |
-| Client-side only testing | Verify server requests triggered correctly |
-| Single scenario testing | Test urban, rural, edge of coverage, out of range |
-| Visual inspection only | Verify data values, counts, distances programmatically |
-
-## Comprehensive Testing Example
-
-```markdown
-### ✅ Correct Approach
-1. ✅ Load page with Prague coords (50.0755, 14.4378) → 3 places at 10km
-2. ✅ Change distance 10km → 100km → 5 places (added 2 at 44km, 83km)
-3. ✅ Change distance 100km → 25km → 3 places (removed beyond 25km)
-4. ✅ Rural coordinates (49.2, 15.5) → 0 places, auto-expanded to 100km
-5. ✅ Verified filter changes trigger new server requests
-```
-
-## Post-Implementation Browser Testing
-
-After completing any feature:
-
-1. Start dev server (see `project.instructions.md` for app/port details).
-2. Open browser to the dev URL.
-3. Test all critical user flows with the project's E2E testing tool (see the **e2e-testing** skill).
-4. Test edge cases (empty results, max/min values, errors).
-5. Document results with screenshots.
-
-### Verify Before Completion
-
-- [ ] Opened app in browser
-- [ ] Tested all interactive elements
-- [ ] Verified data changes match expectations
-- [ ] Checked edge cases
-- [ ] Confirmed empty states display correctly
-- [ ] **Tested at all project-defined responsive breakpoints**
-- [ ] **No horizontal overflow or layout breakage at any breakpoint**
-- [ ] Taken screenshots of key scenarios
-- [ ] Verified URL parameters are correct
+| Testing only initial page load | Test filter changes and different results |
+| Assuming filters work because they render | Verify each option changes results |
+| Client-side only | Verify server requests are triggered |
+| Single scenario | Test urban, rural, edge, out-of-range |
+| Visual inspection only | Verify data values programmatically |
+
+## Post-Implementation Checklist
+
+- [ ] Dev server running; app opened in browser
+- [ ] All interactive elements tested
+- [ ] Data changes verified (not just visual)
+- [ ] Edge cases: empty states, max/min values, errors
+- [ ] All project-defined responsive breakpoints checked (no overflow/breakage)
+- [ ] URL parameters correct
+- [ ] Screenshots taken of key scenarios
 
 ## Commands
 
-Resolve exact test commands via the **codebase-tool** skill. Common tasks:
-
-- Run project tests
-- Run with coverage
-- Update snapshots
-- Run affected tests only
+Resolve exact commands via the **codebase-tool** skill (run tests, run with coverage, update snapshots, run affected only).

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

@@ -3,14 +3,8 @@ name: validation-gates
 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 .opencastle/ directory instead. -->
-
 # Validation Gates
 
-Canonical reference for validation gates shared across all orchestration workflows. Prompt templates reference this skill to avoid duplication.
-
-**Gate summary:**
-
 | Gate | Name | Runs When |
 |------|------|-----------|
 | 1 | Secret Scanning | Every delegation |
@@ -24,209 +18,84 @@ Canonical reference for validation gates shared across all orchestration workflo
 | 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)
+> Inherits: [never-expose-secrets](../../snippets/never-expose-secrets.md)
 
-### 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
+Scan every diff **before** any other gate.
 
 ## Gate 2: Deterministic Checks
 
-Run for every affected project (resolve exact commands via the **codebase-tool** skill):
-
-- **Lint** (with auto-fix)
-- **Test**
-- **Build**
-
-All must pass with zero errors. Run for **every** project that consumed modified files, not just the primary project.
+Run for every affected project (resolve exact commands via the **codebase-tool** skill): lint (with auto-fix), test, build. All must pass with zero errors.
 
 ## 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
+- **Warning** — log in delegation record; investigate partition drift if unexpected
+- **Escalate** — STOP. Verify partition; split or revert; mandatory fast review (no auto-PASS)
 
-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
+**Sensitive files** (always Warning regardless of line count): auth/middleware (`middleware.ts`, `auth.ts`, `**/auth/**`), DB migrations/RLS, security headers/CSP (`next.config.*`, `vercel.json`), env schemas (`.env.example`, `env.ts`), CI/CD (`.github/workflows/**`), package 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)
+| Check | Tool | Pass Criteria | On Failure |
+|-------|------|---------------|------------|
+| Vulnerability | `npm audit` | No new high/critical | BLOCK — use patched version or alternative |
+| License | — | MIT, Apache-2.0, BSD-*, ISC | Flag for human review (non-blocking) |
+| Bundle size | — | Frontend pkgs ≤50KB gzipped | SHOULD-FIX; blocking if >200KB |
+| Duplicates | — | No overlap with existing deps | SHOULD-FIX |
+| Maintenance | — | Updated <2yr, ≥100 weekly DLs | Flag |
 
-> **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.
+## Gate 5: Fast Review
 
-After gates 1–4 pass:
+> **HARD GATE.** Every delegation must pass. Spawn a reviewer sub-agent; PASS → proceed; FAIL → re-delegate (up to 2 retries); 3× FAIL → Gate 9 panel. Load **fast-review** skill.
 
-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 9)
+**Auto-PASS** (skip reviewer): pure research with no code changes; only `.md` files modified; all deterministic gates passed AND ≤10 lines across ≤2 files AND no sensitive files touched.
 
-The reviewer validates: acceptance criteria met, file partition respected, no regressions, type safety, error handling, security basics, and edge cases.
+> **Sensitive file override:** Sensitive files (Gate 3 list) never get auto-PASS, even for 1-line changes.
 
-**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 AND **no sensitive files were touched** (see Gate 3 sensitive file list)
+## Gate 6: Cache Clearing
 
-> **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.
+Clear framework and task runner caches before starting the dev server. See **codebase-tool** skill.
 
-## Gate 6: Cache Clearing (BEFORE Browser Testing)
+## Gate 7: Browser Testing
 
-**Always clear before testing.** Testing stale code wastes time and produces false results.
+> **HARD GATE:** UI changes are NOT done without screenshots in Chrome proving the feature works.
 
-Clear framework caches and task runner caches before starting the dev server for browser testing. See the **codebase-tool** skill for cache-clearing commands.
+1. Start dev server (see **codebase-tool** skill)
+2. Verify all acceptance-criteria items render and behave correctly
+3. Test responsive breakpoints; verify empty, error, and loading states
+4. Capture screenshots of key states (REQUIRED)
 
-## 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.
-
-1. **Start the dev server** — use the project's serve command (see the **codebase-tool** skill) — wait for it to be ready
-2. **Navigate to affected pages** — Verify the new feature renders correctly
-3. **Verify SPECIFIC features** — Check every feature listed in the acceptance criteria. If the criteria say "icons, groups, and AND/OR toggle", you must see all three in the browser
-4. **Test interactions** — Click buttons, fill forms, toggle filters, submit data
-5. **Test responsive** — Resize to each breakpoint defined in your project's testing config
-6. **Test edge cases** — Empty states, error states, loading states, long content
-7. **Screenshot evidence (REQUIRED)** — Take screenshots of key states. These are mandatory proof
-
-> **Anti-pattern:** Testing only at desktop width and assuming responsive classes work. They can be wrong — always verify at all defined breakpoints.
-
-Load the **browser-testing** skill for Chrome MCP commands, breakpoint details, and reporting format.
+Load the **browser-testing** skill for Chrome MCP commands, breakpoints, and reporting format.
 
 ## Gate 8: Regression Testing
 
-New features must not break existing functionality:
-
-1. **Run full test suite** for affected projects — not just the new tests
-2. **Browser-test adjacent pages** — If you changed a shared component, test pages that use it
-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
+1. Run full test suite for all affected projects
+2. Browser-test adjacent pages; verify navigation, routing, and back-button
+3. Check shared components in all consuming apps if a shared library changed
 
-## Gate 9: Panel Review (High-Stakes Only)
+## Gate 9: Panel Review
 
-Use the **panel-majority-vote** skill for:
+Use the **panel-majority-vote** skill for: security-sensitive changes, DB migrations, architecture decisions/large refactors, complex business logic without comprehensive tests.
 
-- Security-sensitive changes (auth flows, RLS policies, API endpoints)
-- Database migrations that alter production data or schema
-- Architecture decisions or large refactors affecting multiple libraries
-- Complex business logic without comprehensive test coverage
+On BLOCK: extract MUST-FIX items, re-delegate, re-run panel. Max 3 attempts, then escalate to Architect.
 
-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
 
-## Gate 10: Final Smoke Test (Feature-Level)
+> Runs once after ALL tasks are Done.
 
-> 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.
-
----
+1. Full build + full test suite from clean state
+2. End-to-end browser walkthrough (loading, empty, populated, error states, transitions)
+3. Cross-task integration check
+4. Final responsive sweep (if UI)
 
-## Universal Completion Checklist
-
-Use this checklist for any orchestration workflow:
-
-- [ ] **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 (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
-- [ ] Known issues updated if new limitations were discovered
+**Skip for:** non-UI with comprehensive tests, or single-task features (Gate 8 covers those). On failure: re-delegate the specific failing integration only.

package/src/orchestrator/snippets/base-output-contract.md

@@ -0,0 +1,14 @@
+# Base Output Contract
+
+Every specialist agent 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](discovered-issues-policy.md)
+- **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](../snippets/base-output-contract.md) for the standard closing items.`

package/src/orchestrator/snippets/discovered-issues-policy.md

@@ -0,0 +1,15 @@
+# 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 unrelated to the current task:
+
+1. **Check if already tracked:**
+   - Search `.opencastle/KNOWN-ISSUES.md` for a matching entry
+   - If task tracker tools are available, search for open bugs
+2. **If found tracked** — skip it, continue with your current work
+3. **If NOT tracked** — you must act:
+   - **Unfixable limitation** (third-party, platform, upstream) → add to `.opencastle/KNOWN-ISSUES.md` with: Issue ID, Status, Severity, Evidence, Root Cause, Solution Options
+   - **Fixable bug** → create a tracker ticket with label `bug`, priority, symptoms, reproduction steps, and affected files. If no tracker tools available, add a `**Discovered Issues**` section to your output.
+
+Never assume a pre-existing issue is somebody else problem. If it is not tracked, track it.

package/src/orchestrator/snippets/logging-mandatory.md

@@ -0,0 +1,11 @@
+# Logging Is Mandatory
+
+> **⛔ HARD GATE — Constitution rule #6.** Every agent MUST log every session to `.opencastle/logs/events.ndjson`. No exceptions. No threshold. No "too small to log."
+
+- Log **before yielding** to the user — logging is the LAST action before responding.
+- Log **per task**, not per conversation. Multiple tasks = multiple records.
+- Never batch-log retrospectively across sessions.
+- Use `opencastle log --type session ...` for session records.
+- Verify the append succeeded: `tail -1 .opencastle/logs/events.ndjson`.
+
+See the **observability-logging** skill for full CLI commands, record schemas, and the pre-response checklist.

package/src/orchestrator/snippets/never-expose-secrets.md

@@ -0,0 +1,22 @@
+# Never Expose Secrets
+
+> **HARD GATE — Constitution rule 1.** No tokens, keys, passwords, or connection strings in code, logs, commits, or terminal output. Use environment variables.
+
+## What to scan
+
+- AWS keys (AKIA...), API tokens (sk-..., ghp_...), private keys, database URIs
+- Hardcoded password, secret, api_key, apiKey, token assignments (not just references)
+- .env file contents copied into source files
+- Base64-encoded secrets
+
+## On detection
+
+- **BLOCK immediately** — flag the specific file and line number.
+- Re-delegate with explicit instruction to use environment variables.
+- If already committed, **rotate 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