diff --git a/.cursor/rules/agent-workflow.mdc b/.cursor/rules/agent-workflow.mdc index 366b526..ad9bbad 100644 --- a/.cursor/rules/agent-workflow.mdc +++ b/.cursor/rules/agent-workflow.mdc @@ -48,15 +48,16 @@ When you're given a per-PR task prompt from `plans/CURSOR-PROMPTS-*.md`: - **Implement in the listed order.** Do not reshape the PR or roll multiple PRs together. - **Match named tests verbatim.** When the plan §4 table lists - `test__`, that is the exact name to use. Test - count must match the prompt's claim. + `test__`, that is the exact name to use. If you + add, drop, or rename tests, update the plan/prompt text in the same + change so reviewers are not chasing a stale list. - **No drive-by lint fixes.** Removing an unused `import` in a file the PR doesn't otherwise touch is still a scope leak. If a file isn't in the deliverables list, don't touch it. - **PR description must include**: scope statement, manual evidence - (with the exact command from the prompt), test count, and any - intentional design divergences from sibling PRs called out - explicitly so the reviewer doesn't flag them as bugs. + (with the exact command from the prompt), and any intentional design + divergences from sibling PRs called out explicitly so the reviewer + doesn't flag them as bugs. ## Editing rules diff --git a/.cursor/skills/plan-project-scope/SKILL.md b/.cursor/skills/plan-project-scope/SKILL.md index 24eb300..c90ee2a 100644 --- a/.cursor/skills/plan-project-scope/SKILL.md +++ b/.cursor/skills/plan-project-scope/SKILL.md @@ -41,7 +41,8 @@ Strong plans in this repo consistently include: - upfront **Status** and dependency context (`Depends on`, if applicable) - a clear **Goal** section with concrete expected outcomes - explicit **Principles (do not relitigate in review)** to freeze key decisions -- a **PR breakdown overview table** (scope, ontology bump, files, tests, dependency order) +- a **PR breakdown overview table** (scope, ontology bump, areas of concern, tests, dependency order) +- **Areas of concern column:** short **risk/review lens** (what to double-check or where coupling is likely). **Not** a module allowlist, **not** exhaustive, and **not** a substitute for the per-PR **File-by-file changes** section (that section remains the touch-scope contract) - per-PR sections with: - file-by-file changes - named tests (verbatim test function names where possible) @@ -72,7 +73,7 @@ Depends on: . - ## PR breakdown - overview -| PR | Scope | Ontology bump | Files touched (approx) | Test buckets | Independent of | +| PR | Scope | Ontology bump | Areas of concern | Test buckets | Independent of | | --- | --- | --- | --- | --- | --- | | PR-X1 | ... | ... | ... | ... | ... | @@ -128,6 +129,7 @@ Landing order: **X1 -> X2 -> X3**. - Name tests exactly when feasible; avoid vague "add tests". - Call out ontology bump and re-index impact for schema/enrichment changes. - Keep "Out of scope" strict; use it to prevent scope creep during implementation. +- Treat **Areas of concern** as **heads-up text for reviewers** (coupling, regression risk, semantic hotspots). Do **not** phrase it as “only these modules” — honest implementation may touch adjacent files; when that happens, update the **File-by-file changes** list and **Out of scope** so the contract stays clear. - Do not add compatibility shims unless explicitly requested. ## Per-PR execution prompt option @@ -139,7 +141,7 @@ Each PR prompt should include: - branch/base - in-scope deliverables - out-of-scope guardrails -- explicit test count/commands +- pytest commands and evidence expectations (avoid hard totals that go stale) - definition of done and PR title convention Use `plans/completed/CURSOR-PROMPTS-TIER1B.md` as the structural reference. diff --git a/.cursor/skills/plan-project-scope/examples.md b/.cursor/skills/plan-project-scope/examples.md index 5b28961..7c036bd 100644 --- a/.cursor/skills/plan-project-scope/examples.md +++ b/.cursor/skills/plan-project-scope/examples.md @@ -15,15 +15,17 @@ as a multi-PR sequence. This file is plan-only and does not implement code. ```markdown ## PR breakdown - overview -| PR | Scope | Ontology bump | Files touched (approx) | Test buckets | Independent of | +| PR | Scope | Ontology bump | Areas of concern | Test buckets | Independent of | | --- | --- | --- | --- | --- | --- | -| PR-X1 | schema + extraction | 9 -> 10 | 4-5 | extraction + schema | prerequisite only | -| PR-X2 | matcher integration | none | 2-3 | regression + continuity | PR-X1 | -| PR-X3 | MCP tool + docs | none | 3-4 | tool filters + docs | PR-X1 | +| PR-X1 | schema + extraction | 9 -> 10 | graph DDL vs writer drift; extraction edge cases | extraction + schema | prerequisite only | +| PR-X2 | matcher integration | none | ambiguous matches; query-layer churn | regression + continuity | PR-X1 | +| PR-X3 | MCP tool + docs | none | tool contract vs docs drift; operator confusion | tool filters + docs | PR-X1 | Landing order: **X1 -> X2 -> X3**. ``` +The **Areas of concern** cells are **review hints** (risks, coupling), not a filename allowlist and not the authority on what may be edited — use the per-PR **File-by-file changes** section for that. + ## 3) Per-PR section skeleton ```markdown diff --git a/.cursor/skills/plan-prompts/SKILL.md b/.cursor/skills/plan-prompts/SKILL.md index 4936f2b..7c02930 100644 --- a/.cursor/skills/plan-prompts/SKILL.md +++ b/.cursor/skills/plan-prompts/SKILL.md @@ -22,7 +22,7 @@ Do not use this skill if there is no plan yet. Write/update the plan first. Before writing prompts, confirm: 1. Source plan file path (for example `plans/PLAN-XYZ.md`). 2. PR list and landing order from the plan. -3. Any fixed constraints (test count expectations, files not to touch, branch naming). +3. Any fixed constraints (branch naming, files or areas not to touch). If already present in the plan, do not ask again. @@ -41,7 +41,7 @@ Write one file: Include: - status line - one section per PR in plan landing order -- `Branch`, `Base`, `Plan section`, estimated diff size +- `Branch`, `Base`, `Plan section` - `@-files` list for context attachment - copy-paste `Prompt` block with strict scope contract @@ -52,7 +52,7 @@ Each PR prompt must include all of: - **Out of scope (do NOT touch)** list mirroring plan boundaries - **Deliverables** numbered and testable - **`## Tests to run (iteration loop)`** — pytest **file** subset for fast local iteration (see below); must appear **after Deliverables and before the full Tests section** -- **Tests** command and expected result format for the full or plan-required run (counts only if known) +- **Tests** command and expected signals (pass/fail, skips, fixtures); avoid hard totals that go stale across branches - **Sentinel checks** (`rg` patterns) where scope enforcement is critical - **Manual evidence** commands when plan requires runtime proof - **Definition of Done** checklist with PR title + branch convention @@ -84,7 +84,6 @@ This heading must stay verbatim so reviewers (and the repo **`pr-review`** skill **Branch:** `feat/` off ``. **Base:** ``. **Plan section:** `plans/PLAN-.md` §
. -**Estimated diff size:** ~ files, ~ LOC. **Attach (`@-files`):** - `@plans/PLAN-.md` @@ -118,7 +117,7 @@ Docs-only PRs (UC15): use a single bullet such as *(none — docs-only change; f ## Tests Run: `` -Expected: +Expected: ## Sentinel checks - `` diff --git a/.cursor/skills/plan-prompts/examples.md b/.cursor/skills/plan-prompts/examples.md index 613f624..9870b3d 100644 --- a/.cursor/skills/plan-prompts/examples.md +++ b/.cursor/skills/plan-prompts/examples.md @@ -16,7 +16,6 @@ Status: **active**. One prompt per PR; each prompt is self-contained. **Branch:** `feat/topic-x1` off `master`. **Base:** `master`. **Plan section:** `plans/PLAN-TOPIC.md` § PR-X1. -**Estimated diff size:** ~4 files, ~300 LOC. **Attach (`@-files`):** - `@plans/PLAN-TOPIC.md` diff --git a/.cursor/skills/plan-prompts/reference.md b/.cursor/skills/plan-prompts/reference.md index bd20214..8372353 100644 --- a/.cursor/skills/plan-prompts/reference.md +++ b/.cursor/skills/plan-prompts/reference.md @@ -5,7 +5,7 @@ Use this when converting `PLAN-*` into `CURSOR-PROMPTS-*`. ## Core quality bar 1. Prompt is self-contained and executable by another agent. -2. Scope is locked to one PR section only. +2. Scope stays within one PR section only. 3. Out-of-scope is explicit and enforceable. 4. Deliverables are concrete and numbered. 5. **Iteration subset** (`## Tests to run (iteration loop)`) lists `tests/test_*.py` bullets with one-line rationales (or UC15 docs-only line) between Deliverables and Tests. diff --git a/AGENTS.md b/AGENTS.md index 5f998a0..6692dd0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -126,10 +126,11 @@ template): - Treat the prompt's **Out of scope** list as binding. Sentinel grep patterns in the prompt must return zero on `git diff master..HEAD`. - Implement deliverables in the listed order; don't reshape the PR. -- Match the prompt's expected test count and named tests verbatim. -- PR description must include: scope statement, manual evidence - (with the exact command from the prompt), test count, and - intentional design divergences flagged. +- Match named tests verbatim when the prompt lists `test_*` names; if + the test set changes, update the prompt/plan text in the same change. +- PR description must include: scope statement, manual evidence (with + the exact command from the prompt), and intentional design + divergences flagged. - No drive-by lint fixes (unused imports, formatting nits in unrelated files). They violate the per-PR scope contract even when they look harmless.