chore: per-folder CLAUDE.md, OCI PR template, OCI issue forms

.github/ISSUE_TEMPLATE/ddia-finding.yml

@@ -0,0 +1,122 @@
+name: DDIA Finding
+description: An OCI flaw spotted while reading Designing Data-Intensive Applications. Routes reading-time insight into shipped improvements.
+title: "[ddia Ch _] "
+labels: ["ddia-finding", "state/backlog"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Closes the loop between DDIA reading and OCI improvements. Different shape from `dogfood-finding`:
+        - `dogfood-finding` = "I used OCI's tools and they failed me"
+        - `ddia-finding` = "I read DDIA and realized OCI does X wrong"
+
+        Be precise. Recruiters reading these issues should see clean DDIA fluency.
+
+  - type: input
+    id: chapter
+    attributes:
+      label: DDIA chapter
+      description: Which chapter triggered this. Update the title prefix to match (e.g. `[ddia Ch 5]`).
+      placeholder: "Ch 5 - Replication"
+    validations:
+      required: true
+
+  - type: input
+    id: concept
+    attributes:
+      label: Specific concept
+      description: Which section or term inside that chapter. Be precise.
+      placeholder: "Read-after-write consistency under async replication"
+    validations:
+      required: true
+
+  - type: input
+    id: surface
+    attributes:
+      label: OCI surface affected
+      description: Which file, service, or design decision is wrong. Absolute path from repo root preferred.
+      placeholder: "backend/services/search.py, Pinecone upsert path"
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: stack
+    attributes:
+      label: Stack
+      options:
+        - label: backend
+        - label: frontend
+        - label: mcp-server
+        - label: cross-cutting
+
+  - type: textarea
+    id: whats-wrong
+    attributes:
+      label: What is wrong (DDIA-grounded)
+      description: 2-4 sentences. Lead with the DDIA principle, then how OCI violates it. No vibes.
+      placeholder: |
+        DDIA Ch 5 argues that asynchronous replication breaks read-after-write within a session unless reads are pinned to the leader for a brief window. OCI's search endpoint writes to Pinecone (async upsert) then can re-read in the same request via the agent loop. Users see stale results immediately after indexing, even though the API returned 200. The right shape is reading metadata from Supabase (authoritative) within the staleness window, or pinning reads after writes.
+    validations:
+      required: true
+
+  - type: textarea
+    id: fix-sketch
+    attributes:
+      label: Proposed fix sketch
+      description: 2-3 sentences OR write "needs ADR via /oci-design". Do not overdesign here.
+      placeholder: needs ADR via /oci-design - the right consistency boundary is non-trivial
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: DDIA-aligned acceptance criteria
+      description: Each criterion ties back to a DDIA principle. This is what makes the fix verifiably correct, not just "looks better."
+      placeholder: |
+        - [ ] Read-after-write within the same request returns the freshly indexed result (DDIA Ch 5 RYW guarantee)
+        - [ ] Cross-session reads document staleness window in the ADR
+
+  - type: dropdown
+    id: reliability
+    attributes:
+      label: Reliability impact
+      description: How badly does the current state hurt reliability (DDIA Ch 1 pillar)?
+      options:
+        - none
+        - minor
+        - major
+        - critical
+    validations:
+      required: true
+
+  - type: dropdown
+    id: scalability
+    attributes:
+      label: Scalability impact
+      description: How badly does the current state hurt scalability?
+      options:
+        - none
+        - minor
+        - major
+        - critical
+    validations:
+      required: true
+
+  - type: dropdown
+    id: maintainability
+    attributes:
+      label: Maintainability impact
+      description: How badly does the current state hurt maintainability?
+      options:
+        - none
+        - minor
+        - major
+        - critical
+    validations:
+      required: true
+
+  - type: input
+    id: notes
+    attributes:
+      label: Chapter notes file
+      description: Path to your chapter notes for cross-reference.
+      placeholder: "learning/ddia/chapter-5.md"

.github/ISSUE_TEMPLATE/dogfood-finding.yml

@@ -0,0 +1,84 @@
+name: Dogfood Finding
+description: A friction you hit while using OCI's own MCP tools to build OCI. Capture in 60 seconds. Triage later.
+title: "[dogfood] "
+labels: ["dogfood-finding", "state/backlog", "type/fix"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Dogfooding is the forcing function. When OCI's own tools fail you mid-build, file it here in 60 seconds and keep coding. Triage happens during the Sunday `/oci-dogfood` review.
+
+  - type: textarea
+    id: tried
+    attributes:
+      label: What I tried
+      description: The exact tool call or workflow that triggered the friction.
+      placeholder: |
+        codeintel:search_code({
+          "query": "where authentication happens",
+          "repo_id": "78aa181e-2bbb-438b-97ee-9ffd494c4815"
+        })
+    validations:
+      required: true
+
+  - type: textarea
+    id: happened
+    attributes:
+      label: What happened
+      description: Wrong result, slow result, error, or surprising behavior. Paste output if useful.
+      placeholder: Returned 50 results across non-auth files. The actual auth code at `backend/middleware/auth.py` was not in the top 20.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What I expected
+      description: What would have been useful.
+      placeholder: "`backend/middleware/auth.py` in the top 3 results, since it has 'auth' in the path and contains the auth functions."
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Repro steps
+      description: Minimal steps for someone else (or future-you) to reproduce.
+      placeholder: |
+        1. cd into OCI repo, ensure MCP server is connected
+        2. Call codeintel:search_code with the query above
+        3. Note auth.py is not in the top results
+    validations:
+      required: true
+
+  - type: dropdown
+    id: tool
+    attributes:
+      label: Which OCI tool
+      description: The MCP tool that misbehaved.
+      options:
+        - codeintel:search_code
+        - codeintel:get_codebase_dna
+        - codeintel:analyze_impact
+        - codeintel:get_dependencies
+        - other (specify in body)
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: stack
+    attributes:
+      label: Stack the fix likely lives in
+      description: Best guess. Reviewer-arch will refine during triage.
+      options:
+        - label: backend
+        - label: frontend
+        - label: mcp-server
+        - label: cross-cutting
+
+  - type: textarea
+    id: hypothesis
+    attributes:
+      label: Hypothesis (optional)
+      description: If you have a guess about the root cause, capture it so future-you does not re-derive.
+      placeholder: Search reranker weights "auth" too literally and misses semantic matches. Or include_paths filter is dropping middleware/.

.github/ISSUE_TEMPLATE/oci-issue.yml

@@ -0,0 +1,127 @@
+name: OCI Issue (internal)
+description: Track an OCI work item (feat / refactor / chore / docs). For external bug reports use Bug Report; for external feature requests use Feature Request.
+title: "[OCI] "
+labels: ["state/backlog"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Internal OCI work tracker. Every issue here is a candidate for the OCI pipeline (`/oci-design` → `/oci-implement` → `/oci-pipeline` → `/oci-defend` → merge → `/oci-merge-done`).
+
+        Be specific. Vague issues do not earn ADRs and they do not ship.
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why this exists
+      description: What forces this work? Tie to a Wave priority, a dogfood-finding, a DDIA-finding, a customer report, or a security/perf bound that has been hit. One paragraph. No "we want to improve X" - name what changes if we do not ship this.
+      placeholder: |
+        Search latency is 3.6s p95 (OPE-121). MCP tools used in agent loops have a 500ms budget. Without fixing this, the search MCP tool is unusable inline and Greptile / Solid integrations are dead on arrival.
+    validations:
+      required: true
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What ships
+      description: Concrete deliverables, one per bullet. Each bullet is ONE file change or ONE user-visible behavior. Do not bundle.
+      placeholder: |
+        - Replace Cohere reranker with the on-prem cross-encoder in `backend/services/search/rerank.py`
+        - Add `RERANKER_BACKEND` env var to `backend/config/startup_checks.py` (warning only)
+        - Update `mcp-server/api_client.py` to surface reranker name in tool response metadata
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Testable outcomes only. Either a unit test exists OR a manual repro is documented. "Looks good" is not a criterion. "p95 latency under 500ms on /api/v1/search" is.
+      placeholder: |
+        - [ ] `/api/v1/search` p95 < 500ms measured over 100 requests on the OCI-on-OCI corpus
+        - [ ] Reranker name appears in MCP tool response metadata
+        - [ ] Backend tests pass: `cd backend && pytest tests/ -v`
+    validations:
+      required: true
+
+  - type: dropdown
+    id: wave
+    attributes:
+      label: Wave
+      description: Which OCI thesis wave does this serve? `pre-thesis` if filed before `oci/strategy.md` is locked.
+      options:
+        - pre-thesis
+        - "1"
+        - "2"
+        - "3"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: type
+    attributes:
+      label: Type
+      description: Matches commit-message type. Apply the corresponding label after filing.
+      options:
+        - feat
+        - fix
+        - refactor
+        - perf
+        - docs
+        - test
+        - chore
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: stack
+    attributes:
+      label: Stack scope
+      description: Which stacks does this touch? Tick all that apply.
+      options:
+        - label: backend
+        - label: frontend
+        - label: mcp-server
+        - label: cross-cutting (ADR / vault / docs / multi-stack)
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      options:
+        - urgent
+        - high
+        - medium
+        - low
+      default: 2
+    validations:
+      required: true
+
+  - type: dropdown
+    id: adr
+    attributes:
+      label: ADR required?
+      description: Yes for any feat or non-trivial change. No for small fixes / docs / chore. The OCI pipeline refuses to start `/oci-implement` if `adr-required` is set and no ADR exists.
+      options:
+        - "yes - run /oci-design before /oci-implement"
+        - "no - under ADR threshold"
+    validations:
+      required: true
+
+  - type: textarea
+    id: dogfooding
+    attributes:
+      label: Dogfooding signal
+      description: Did using OCI on OCI surface this need? If yes, link the moment or describe the failure. If no, write "no - filed from {plan / brainstorm / customer / regression / DDIA reading}".
+      placeholder: "yes - codeintel:search_code returned irrelevant results when I queried 'auth fallback path' while debugging Bug #1"
+
+  - type: textarea
+    id: related
+    attributes:
+      label: Related
+      description: Wave milestone (when thesis locks), prior ADRs, linked issues, external references.
+      placeholder: |
+        - Wave: pre-thesis (Phase 1 pipeline work)
+        - Prior ADRs: n/a
+        - Linked: #
+        - External: DDIA Ch 1 percentile-vs-average discussion