.cursorrules

# Cursor Rules for Shipyard Repository

## 1-1-1 Workflow Enforcement

### PR Velocity Control
Before creating ANY new Pull Request, you MUST:

1. **Check Current PR Count**: Run `gk mcp list_pull_requests` or equivalent to count open PRs
2. **Enforce Limit**: If there are **more than 5 open PRs** across all repos, STOP and ask the user which PRs to close before proceeding
3. **One PR per Repo**: Do not open more than **1 PR per repository** at a time
4. **Sequential Work**: Do not start new features until existing PRs are merged

### Cleanup First
If asked to create a PR but the backlog exceeds limits:
- List all open PRs with their age
- Recommend closing any PR older than 14 days
- Wait for user confirmation before creating new work

### Stale PR Handling
PRs older than 30 days should be considered stale. When encountered:
- Add comment: "Closing stale PR to clear backlog. Re-open if critical."
- Close the PR
- The `stale.yml` workflow will auto-close PRs after 14 days of inactivity

## Code Quality Standards

### IP and Code Provenance (Strict Mode)
- **NO EXTERNAL COPY-PASTING**: You are explicitly forbidden from copy-pasting code snippets, verbatim algorithms, or utility implementations from public repositories, blogs, or external open-source projects.
- **SINGLE SOURCE OF TRUTH**: Rely exclusively on the current Woven Map codebase as the single source of truth for design patterns, styling, and utility implementations.
- **ORIGIN HEADERS REQUIRED**: For any newly synthesized non-trivial algorithm, you MUST include a provenance comment header (e.g., `// [Origin: Custom implementation for Woven Map - YYYY-MM-DD]`).

### Before Any Commit
- Run `npm run lint` in the vessel directory
- Fix any lint errors before committing
- Test that the dev server starts successfully

### Commit Message Format
- Use conventional commits: `feat:`, `fix:`, `docs:`, `chore:`
- Linear issue keys are optional in commit messages
- If a real issue key is available and useful, use resolution keywords: `Fixes WOV-123`, `Resolves WOV-123`, `Closes WOV-123`
- Example: `feat: add transit overlay`
- Optional Linear-linked example: `feat: add transit overlay — Fixes WOV-42`

### Branch Naming
- Branch names do not require a Linear issue key. If a real key is available and you want linkage, use `wov-123-feature-name`.

### Pull Request Titles
- PR titles do not require a Linear issue key. If a real key is available and you want linkage, `WOV-123 Add new feature` remains acceptable.

### Linear Integration
- This repo is linked to Linear via GitHub webhook — commits and PRs auto-link to issues
- A `release-drafter.yml` action builds changelogs from PR titles and commit messages
- **Do not block commits, branches, or PRs on the presence of a `WOV-` issue key**

## Repository Context

### Active Development
- **Primary App**: Located in `/vessel` (Next.js + TypeScript)
- **Deploy Target**: Vercel (uses `vessel/vercel.json` for build config)
- **Runtime Name**: Raven v3 (astrological AI reasoning engine)
- **Key Directories**:
  - `/vessel/src/lib/raven/` — Core persona, session machine, protocol engine
  - `/vessel/src/app/api/raven-chat/` — Main chat orchestration route
  - `/vessel/src/components/` — React UI components
  - `/scripts/` — Standalone tooling and diagnostics

### Deprecated & Legacy
- **WovenWebApp**: DEPRECATED — do not create PRs or add features there. Consider consolidating into Shipyard if needed; otherwise leave as reference only.

### Project Discovery & Maintainability

#### Sherlog Velocity Framework
Before major feature work or when filing estimates, run:
```bash
npm run sherlog:verify -- --json          # Validate context completeness
npm run sherlog:doctor -- --feature "Feature Name" --json  # Pre-feature readiness check
npm run sherlog:gaps -- --feature "Feature Name" --json    # Identify missing coverage
npm run sherlog:prompt -- "Feature Name"  # Generate implementation guidance
```
Reference docs: `/docs/why-sherlog.md`, `/docs/sherlog-next-steps.md`

#### Project Index & Navigation
- **PROJECT_INDEX.json** — Master inventory of packages, modules, and their relationships. Use this to orient when exploring unfamiliar subsystems.
- **Repomix Archives** — Located in `/Archived Repomixes/` and referenced as `repomix-*.xml` files at repo root. These are snapshots of thematic subsystems (e.g., `repomix-raven-core.xml`, `repomix-vessel-dev-env.xml`).
- **Generating Repo Mixes**: When documenting or sharing subsystem scope, use `repomix` to create themed bundles:
  ```bash
  repomix --config repomix-<feature>.config.json
  ```
  This is more effective than loose file lists for onboarding, PR context, and architectural snapshots.

## Documentation & Artifacts
- Session exports are in `/Captains Logs/` and `/WovenMap Logging/`
- Inspiration & design source in `/Inspiration Folder/` (read-only reference)
- Audit results and decision journals in `/archive/`

## Coverage Integrity Rule

A passing test count does not prove new behavior is covered. When a change introduces new routing, scoring, validation, fallback, or rendering behavior, the release is not verified until tests directly reference the new functions and states.

- Do not report existing tests as proof of a new deliverable unless at least one test exercises the new behavior directly.
- Malformed non-empty astrology input must not collapse into quiet — emit `measurement_degraded`, not `measured_quiet`.
- If a change reorders lead contact or primary driver, prove measurement math is byte-identical unless the change explicitly intends to alter measurement.
- Release gate: direct branch tests + degraded-path tests + validator tests + strict preflight pass before pushing production-pipeline changes.