Expand Cursor agent rules and resolve workflow contradictions.

Add modular .cursor/rules for requirements gates, tickets, TDD, and
verification; tighten plan-first and multi-agent flows; slim AGENTS.md
to an index aligned with make lint/mypy/test checks.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: northdpole

.cursor/rules/autonomous-workflow.mdc

@@ -1,20 +1,19 @@
 ---
-description: Autonomous execution defaults for OpenCRE
+description: End-to-end execution policy after plan approval
 alwaysApply: true
 ---
 
 # OpenCRE Autonomous Workflow
 
-Policy (CI/PR, git, validation order, critical paths): see `AGENTS.md`.
+Policy: see `AGENTS.md`. Verification: see `verifiable-goals.mdc`.
 
 - For big changes, wait for human plan approval (`multi-agent-workflow.mdc` Phase 1) before editing.
-- After plan approval, execute tasks end-to-end unless blocked by auth/secrets, destructive actions, or material plan deviations.
-- Prefer small, safe changes and avoid unrelated refactors.
+- After approval, execute end-to-end unless blocked by auth/secrets, destructive actions, or material plan deviations.
+- Prefer small, safe changes; avoid unrelated refactors.
 - Use `Makefile` targets when possible.
-- For substantive code changes, run `make lint`, `make mypy`, and `make test` before handoff (skip only when clearly irrelevant and explain why).
-- If any check reports failures introduced by your changes, fix them before handoff.
-- If commit verification depends on shell initialization, run verification commands in a zsh-compatible shell context so environment-dependent checks are not skipped.
-- Run long commands in the background and monitor until completion.
-- Do NOT commit or push unless explicitly asked (except when the user explicitly requests CI auto-fix / PR creation; see `AGENTS.md`).
+- **Always run lint, mypy, and tests after substantive changes; iterate until green.** Show evidence in handoff.
+- If commit verification depends on shell initialization, use a zsh-compatible shell context.
+- Run long commands in background; monitor until completion.
+- Do NOT commit or push unless explicitly asked.
 - In commits do not add "made with cursor" lines.
-- At handoff, report: changed files, checks run, and any residual risks.
+- On substantive changes, recommend or run judge/subagent review before handoff.

.cursor/rules/complete-ticket.mdc

@@ -0,0 +1,26 @@
+---
+description: Requires complete tickets before coding - asks clarifying questions if requirements are missing
+globs: "**/*.{md,txt}"
+alwaysApply: false
+---
+
+# Complete Ticket Requirement
+
+When the user submits a ticket or task via a `.md` or `.txt` file (including `AGENTS.md`):
+
+1. **Check** for: goal, success criteria, context, constraints — same rules as `requirements-gate.mdc`
+2. **If missing** → ask clarifying questions; offer the **Requirements template** in `requirements-gate.mdc`; do NOT code
+3. **If complete** → follow the decision tree in `multi-agent-workflow.mdc`:
+   - Trivial (typo, rename, one-liner) → implement directly
+   - Non-trivial → Plan Mode per `plan-first-workflow.mdc` or Phase 1 per `multi-agent-workflow.mdc` when both apply
+   - Wait for approval before implementation when planning is required
+4. **Never assume** missing details — see `never-assume.mdc`
+
+Verification after implementation: `verifiable-goals.mdc`. Tests for new behavior: `tdd-workflow.mdc`.
+
+## Coding standards (not covered elsewhere)
+
+- **Stack:** Python for backend/application code; TypeScript for new frontend code (`application/frontend/`).
+- **Error handling:** Handle expected failure paths explicitly; avoid silent failures; return or raise meaningful errors.
+- **Async (frontend):** Prefer `async`/`await` over raw Promise chains or callbacks in new TypeScript.
+- **Clean code:** Small functions, clear names, match surrounding module conventions; no drive-by refactors.

.cursor/rules/context-management.mdc

@@ -0,0 +1,29 @@
+---
+description: Keep agent context focused across tasks and stale threads
+alwaysApply: true
+---
+
+# Context Management
+
+## Do
+
+- Use `/clear` between unrelated tasks or features.
+- Reference files with `@path` instead of pasting entire file contents.
+- Use `@Past Chats` to pull in prior work instead of copy-pasting old conversations.
+- Start fresh after **2 failed corrections** on the same issue: `/clear`, then write a better prompt that incorporates what you learned.
+
+## Don't
+
+- Let context accumulate across unrelated features in one long thread.
+- Describe files vaguely when an `@` reference exists.
+- Keep correcting the same mistake in a degrading context — reset instead.
+
+## When context is stale
+
+Signs you should `/clear` and re-prompt:
+
+- Repeated fixes on the same bug without progress
+- Agent confuses requirements from an earlier, unrelated task
+- Plan has drifted significantly from what was approved
+
+After clearing, restate: goal, approved plan (or link to `.cursor/plans/*.md`), relevant `@` files, and acceptance criteria.

.cursor/rules/multi-agent-workflow.mdc

@@ -1,65 +1,72 @@
 ---
-description: Human plans big changes first; agent executes after explicit approval
+description: Two-phase planning for big changes; builder must not be sole judge
 alwaysApply: true
 ---
 
 # Multi-Agent Workflow (Human Plan → Agent Execute)
 
 For **big changes**, split work into two phases. Do not skip Phase 1.
 
-## What Counts as a Big Change
-
-Treat the change as **big** when any of these apply:
+## What counts as a big change
 
 - New feature, new standard importer, or new user-facing capability
 - Expected to touch **3+ files** or **>500 lines** of diff
 - Refactor or migration with behavioral risk
 - Touches critical paths (auth, secrets, production data, payments)
-- Requirements are incomplete or have meaningful product/design choices
+- Incomplete requirements or meaningful product/design choices
+
+Small fixes: single-file bugfix, typo, test-only tweak, clear one-liner → `plan-first-workflow.mdc` only.
+
+## Phase 1 — Human-led planning (no code)
+
+**Stop before editing.**
 
-Small fixes (single-file bugfix, typo, test-only tweak, clear one-liner scope) skip this rule; use `plan-first-workflow.mdc` only.
+1. Acknowledge this is a big change; planning comes first.
+2. Ask minimum questions: goal, data sources, pattern to mirror, acceptance criteria, out of scope.
+3. Draft a plan: steps, `@` file paths, similar code, test/validation plan, risks.
+4. Wait for explicit approval ("proceed", "approved", or confirmed edited plan).
+5. No commits, push, or implementation code in Phase 1. Read-only research is fine.
+   Tests and production code begin in Phase 2 after approval (see `tdd-workflow.mdc`).
 
-## Phase 1 — Human-Led Planning (Agent Facilitates, No Code)
+## Phase 2 — Agent execution
 
-**Stop before editing.** Your job is to help the human produce and approve a plan.
+After approval:
 
-1. **Acknowledge** this is a big change and that planning comes first.
-2. **Ask the human** the minimum questions needed to plan well. Prefer a short numbered list over a long questionnaire. Typical prompts:
-   - What is the goal and definition of done?
-   - What source format / data / URLs does FOOBAR (or the feature) use?
-   - Which existing pattern should we mirror (e.g. a similar importer or route)?
-   - Acceptance criteria and manual checks?
-   - Out of scope / constraints?
-3. **Draft a plan** for the human to edit, including:
-   - Goal and acceptance criteria
-   - Steps in execution order
-   - Files likely touched (with `@`-style paths where helpful)
-   - Similar code to follow
-   - Test and validation plan (`make lint`, `make mypy`, `make test`, import smoke if relevant)
-   - Risks and open questions
-4. **Wait for explicit approval** before Phase 2. Approval looks like: "looks good", "proceed", "approved", or an edited plan the human confirms.
-5. **Do not** create commits, push, or write implementation code during Phase 1. Research and read-only exploration are fine.
+1. Execute per `autonomous-workflow.mdc`.
+2. Follow the approved plan; pause if material deviation is needed.
+3. Implement incrementally; verify as you go (`verifiable-goals.mdc`).
+4. Hand off with checklist including test evidence.
 
-If the human already supplied a complete plan, reflect it back briefly and ask them to confirm before executing.
+## Builder ≠ Judge (required on substantive work)
 
-## Phase 2 — Agent Execution (Autonomous)
+| Role | Responsibility |
+|------|----------------|
+| **Builder** | Implements approved plan |
+| **Judge** | Independent review — edge cases, security, test gaps |
 
-After the human approves the plan:
+Invoke judge via subagent, parallel agent, or fresh context:
 
-1. **Execute end-to-end** per `autonomous-workflow.mdc` and `AGENTS.md`.
-2. **Follow the approved plan**; if you discover a material deviation, pause and ask before continuing.
-3. **Implement in small increments** when possible; run validation as you go.
-4. **Evaluate** against acceptance criteria: run tests, note manual spot-checks for the human.
-5. **Hand off** with the standard checklist (changes, checks, CI status, risks).
+- "Use a subagent to review this change for edge cases and security issues."
 
-## Optional Cursor Agent Window Roles
+Do not mark substantive work complete without independent review or documented reason to skip.
 
-When using parallel agents, map roles to phases:
+**Re-review:** Required only when judge findings change behavior, tests, or security posture materially. Style-only nits fixed in-place do not require a second judge pass.
 
-| Role | Phase | Responsibility |
-|------|-------|----------------|
-| Planner | 1 | Expand prompt into spec + acceptance criteria; human approves |
-| Builder | 2 | Implement approved plan |
-| Evaluator | 2 | Run tests/checks; compare results to acceptance criteria |
+## Decision tree
 
-One agent can cover Builder + Evaluator; Phase 1 still requires human approval before Builder starts.
+```
+User request received
+  │
+  ├─ Missing goal / criteria / context / constraints?
+  │     └─ STOP → ask questions OR offer Requirements template (requirements-gate.mdc)
+  │
+  ├─ Typo / rename / one-sentence fix?
+  │     └─ Implement → quality checks → show evidence
+  │
+  ├─ Multi-file / new feature / refactor / critical path?
+  │     └─ Plan Mode → detailed plan → WAIT for approval → implement
+  │           → quality checks → subagent review → handoff with evidence
+  │
+  └─ Otherwise
+        └─ Brief plan → implement → quality checks → handoff with evidence
+```

.cursor/rules/never-assume.mdc

@@ -0,0 +1,30 @@
+---
+description: Verify or ask — no guessing packages, APIs, patterns, or incomplete code
+alwaysApply: true
+---
+
+# Never Assume
+
+| Do NOT | Instead |
+|--------|---------|
+| Assume package names, API endpoints, DB schema, or file locations | Read the codebase; grep; ask |
+| Add new dependencies without explanation | State why, alternatives considered, and get approval |
+| Use mocks unless explicitly requested | Prefer integration-style tests matching `@application/tests/` patterns |
+| Replace code with placeholders, TODOs, or stubs | Ship complete, working code |
+| Write incomplete implementations | Finish the feature or stop and explain what's blocked |
+| Guess production/staging targets for DB ops | Confirm target app; follow `production-db-ops-safety.mdc` |
+| Commit or push unless asked | Wait for explicit user request |
+
+## Scope and diff discipline
+
+- Minimize scope — smallest correct diff; no drive-by refactors.
+- Match surrounding naming, types, imports, and documentation level.
+- Comments only for non-obvious business logic.
+- Do not add markdown/docs files the user did not ask for.
+- Do not use "made with cursor" or similar in commits.
+
+## OpenCRE conventions
+
+- Mirror patterns in existing code (importers, tests, web routes).
+- Use Makefile targets over ad-hoc commands when available.
+- Prefer `scripts/db/` for production DB operations over raw SQL.

.cursor/rules/plan-first-workflow.mdc

@@ -1,29 +1,54 @@
 ---
-description: Plan with reasoning before substantive code changes
+description: Require Plan Mode and user approval before non-trivial implementation
 alwaysApply: true
 ---
 
 # Plan-First Workflow
 
-Apply before making non-trivial edits that are **not** big enough to trigger `multi-agent-workflow.mdc`.
+Apply before non-trivial edits. When criteria overlap with `multi-agent-workflow.mdc` (e.g. new feature, 3+ files), follow **multi-agent** Phase 1 — it is the stricter superset.
 
-If the change is big (new feature/importer, 3+ files, >500 lines, critical paths), use the human-plan → agent-execute flow there instead of planning and coding in one step.
+## Skip planning only for
 
-## Before Editing
+- Typos, renames, obvious single-line fixes
+- Tasks fully specified with no design choices
 
-- Provide a brief plan with reasoning: goal, steps, files likely touched, and validation approach.
-- Break the problem into smaller steps and think through each separately.
-- If intent is ambiguous, ask before implementing.
-- Check `docs/runbooks/` when the change touches deploy, DB, imports, or ops workflows.
+## MUST plan before implementing when ANY apply
 
-## While Editing
+- New feature or new importer
+- Multi-file change (3+ files) or >500 lines expected
+- Refactor or migration with behavioral risk
+- Touches critical paths (auth, secrets, production data, payments, deploy)
+- Requirements have meaningful design choices
 
-- Only modify code directly relevant to the request.
-- Never replace code with placeholders (e.g. `// ... rest of the processing ...`). Include complete, working code.
-- Prefer referencing existing patterns with file paths (e.g. "similar to `application/web/web_main.py` route handlers") over inventing new conventions.
-- When debugging, state observations first, then reasoning, then the proposed fix.
+## Plan output MUST include
 
-## After Editing
+1. **Goal** — restated in one sentence
+2. **Files** — exact paths to create/modify/delete
+3. **Dependencies** — imports, DB migrations, external APIs, new packages
+4. **Steps** — ordered implementation sequence
+5. **Tests** — new/updated test files and what they assert
+6. **Edge cases** — failure modes, empty input, backwards compatibility
+7. **Verification** — exact commands (`make lint`, `make mypy`, `make test`, etc.)
+8. **Risks** — what could break and how to detect it
 
-- Before handoff, briefly explain key design choices so a reviewer can ask "why this way?" without re-reading the whole diff.
-- Prefer small, reviewable diffs; validate incrementally when possible.
+## Approval gate
+
+After presenting the plan, **wait for explicit user approval** ("proceed", "approved",
+or an edited plan confirmed by the user) before writing implementation code.
+
+After approval, **tests may be written first** per `tdd-workflow.mdc` — failing tests are not "implementation code" for Phase 1 purposes.
+
+Read-only research (grep, read files, explore codebase) is allowed during planning.
+
+Save approved plans to `.cursor/plans/<feature>.md` when scope is substantial.
+
+## Before editing (Agent Mode)
+
+- Brief plan with reasoning: goal, steps, files touched, validation approach.
+- Break into smaller steps; check `scripts/db/` and `scripts/` for deploy/DB/import ops.
+
+## While editing
+
+- Only modify code relevant to the request.
+- Never use placeholders — include complete, working code.
+- **Reference patterns specifically:** e.g. mirror `@application/utils/external_project_parsers/parsers/pci_dss.py`, tests like `@application/tests/pci_dss_parser_test.py`.

.cursor/rules/requirements-gate.mdc

@@ -0,0 +1,53 @@
+---
+description: Stop and ask clarifying questions before coding when requirements are incomplete
+alwaysApply: true
+---
+
+# Requirements Gate
+
+If ANY of the following is missing or ambiguous, **STOP and ask clarifying questions**.
+Do NOT write, edit, or delete code until the gaps are filled.
+
+| Required | What to ask |
+|----------|-------------|
+| **Clear goal** | What outcome does the user want? What problem are we solving? |
+| **Verifiable success criteria** | Which checks must pass? (tests, typecheck, linter, CI, manual steps) |
+| **Context references** | Which files, modules, or prior chats apply? Prefer `@path/to/file` refs when ambiguous. |
+| **Constraints** | Out of scope, performance, compatibility, no new deps, prod DB safety, etc. |
+
+## Context references — when `@` refs are required
+
+- **Satisfied without `@`** when the message names specific paths, modules, or patterns clearly (e.g. "add tests for `application/utils/gap_analysis.py`").
+- **Ask for `@` refs** when multiple files could apply, the pattern to mirror is unclear, or prior chat/issue context is needed.
+
+## Skip the gate only when
+
+The request is fully specified in one sentence with obvious success criteria and unambiguous context, e.g.
+"Fix typo in README line 42" or "Rename `foo` to `bar` in `application/utils/gap_analysis.py`."
+
+## Requirements template (offer when info is missing)
+
+```
+## Task
+<One-sentence goal>
+
+## Success criteria (all must pass)
+- [ ] `make lint`
+- [ ] `make mypy`
+- [ ] `make test` (or targeted: `python -m unittest application/tests/<module>_test.py`)
+- [ ] `make frontend` / `yarn build` (if frontend touched)
+- [ ] CI green (`gh pr checks` or Actions UI)
+- [ ] Other: ___
+
+## Context
+- Files: @path/to/relevant/file.py
+- Pattern to mirror: @path/to/similar/implementation.py
+- Prior work: @Past Chats / issue # / PR #
+
+## Constraints
+- In scope: ___
+- Out of scope: ___
+- Dependencies: none / explain before adding
+- Mocks: allowed / not allowed
+- Production DB: N/A / read-only / destructive (requires explicit confirmation)
+```

.cursor/rules/tdd-workflow.mdc

@@ -0,0 +1,30 @@
+---
+description: Test-first workflow for new behavior, importers, and API changes
+alwaysApply: true
+---
+
+# TDD Workflow
+
+Use for new behavior, bug fixes with clear reproduction, and importers/API changes where expected I/O is known.
+
+Skip for: typos, pure refactors with existing test coverage, config-only changes.
+
+## Timing relative to planning
+
+- **After plan approval** (or immediately for trivial fixes that skip planning): write failing tests, then implementation.
+- Do not write production code before plan approval when planning is required.
+
+## Loop
+
+1. **Write tests first** from expected input/output or acceptance criteria.
+2. **Run tests and confirm they fail** for the right reason. Do not write implementation yet.
+3. **Commit tests** only when the user explicitly asks to commit mid-flow.
+4. **Implement** the minimum code to pass tests. Do not modify tests to make them pass unless requirements changed (say so explicitly).
+5. **Iterate** until `make test` (and lint/mypy) pass.
+6. **Commit implementation** when the user asks.
+
+## OpenCRE conventions
+
+- Follow patterns in `@application/tests/` (e.g. `@application/tests/pci_dss_parser_test.py` for importers).
+- Use test DB setup from existing parser/web tests; avoid unnecessary mocks when integration-style tests match the codebase.
+- Prefer one focused test class per behavior area.