From a73e104a1efd39f5c77524967904250b7c73e64c Mon Sep 17 00:00:00 2001 From: Ambient Code Bot Date: Thu, 16 Apr 2026 22:56:56 -0400 Subject: [PATCH 1/2] feat: add cross-cutting development conventions from post-v0.2.0 learnings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Analyzed 23 PRs merged since v0.2.0 and extracted 5 cross-cutting development guidelines into CLAUDE.md Critical Conventions. Each prevents a specific class of rework observed in recent PRs: - Design for extensibility before adding items (PR #1333→#1326) - Verify contracts and references (PR #1325, #1329) - CI/CD security (PR #1310, #1334, #1331) - Full-stack awareness (PR #1282, #1289) - Separate configuration from code (PR #1337) Also renames "Critical Context" → "Critical Conventions" with a description clarifying these are cross-cutting rules vs. component-specific ones. Includes HTML triage dashboard used for HITL review of proposed guidelines. Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 18 +- docs/knowledge-finder-triage.html | 318 ++++++++++++++++++++++++++++++ 2 files changed, 335 insertions(+), 1 deletion(-) create mode 100644 docs/knowledge-finder-triage.html diff --git a/CLAUDE.md b/CLAUDE.md index efcf8ca90..437bb4c6e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -90,7 +90,8 @@ Benchmark notes: ## Critical Conventions -Rules that apply across ALL components. Per-component details live in component DEVELOPMENT.md files. +Cross-cutting rules that apply across ALL components. Component-specific conventions live in +component DEVELOPMENT.md files (see [BOOKMARKS.md](BOOKMARKS.md) > Component Development Guides). - **User token auth required**: All user-facing API ops use `GetK8sClientsForRequest(c)`, never the backend service account - **No tokens in logs/errors/responses**: Use `len(token)` for logging, generic messages to users @@ -99,6 +100,21 @@ Rules that apply across ALL components. Per-component details live in component - **No `any` types in frontend**: Use proper types, `unknown`, or generic constraints - **Feature flags strongly recommended**: Gate new features behind Unleash flags. Use `/unleash-flag` to set up - **Conventional commits**: Squashed on merge to `main` +- **Design for extensibility before adding items**: When building infrastructure that will have + things added to it (menus, config schemas, API surfaces), build the extensibility mechanism + first — conditional rendering, feature-flag gating, discovery. Retrofitting causes rework. +- **Verify contracts and references**: Before building on an assumption (env var exists, path is + correct, URL is reachable), verify the contract. After moving anything, grep scripts, workflows, + manifests, and configs — not just source code. +- **CI/CD security**: Never use `pull_request_target` (grants write access to forked PR code). + Never hardcode tokens — use `actions/create-github-app-token`. For automated pipelines: + discovery → validation → PR → auto-merge. +- **Full-stack awareness**: Before building a new pipeline, check if an existing one can be + reused. Auth/credential/API changes must update ALL consumers (backend, CLI, SDK, runner, + sidecar) in the same PR. +- **Separate configuration from code**: Config changes must not require code changes. Externalize + via env vars, ConfigMaps, manifests, or feature flags. If a value varies across environments + or changes over time, it's config, not code. Component-specific conventions: - Backend: [DEVELOPMENT.md](components/backend/DEVELOPMENT.md), [ERROR_PATTERNS.md](components/backend/ERROR_PATTERNS.md), [K8S_CLIENT_PATTERNS.md](components/backend/K8S_CLIENT_PATTERNS.md) diff --git a/docs/knowledge-finder-triage.html b/docs/knowledge-finder-triage.html new file mode 100644 index 000000000..b40643aec --- /dev/null +++ b/docs/knowledge-finder-triage.html @@ -0,0 +1,318 @@ + + + + + +Knowledge Finder — Post-v0.2.0 Triage + + + + +
+

Knowledge Finder — Post-v0.2.0 Triage

+

23 PRs analyzed since v0.2.0 (April 10–17, 2026). 6 consolidated guidelines extracted. Each shows its proposed destination based on impact radius.

+
+
5
→ CLAUDE.md
+
1
→ Component Guide
+
23
PRs Analyzed
+
+
+ +
+ Triage checklist — for each item, ask: +
    +
  1. Is it cross-cutting enough for its proposed destination?
    2. +
  2. Would an agent knowing this have avoided the rework described?
    3. +
  3. Is the wording concise and actionable?
    4. +
  4. Does it duplicate anything already in Critical Conventions?
    5. +
+
+ + +

→ CLAUDE.md Critical Conventions (5 cross-cutting guidelines)

+ + +
+
+
+
Design for extensibility before adding items
+
+ → CLAUDE.md + PR #1333 → #1326 +
+
+
+
PR #1333 built menu infrastructure with unconditional separator. PR #1326 had to rework it to make separators conditional and feature-flag-gated.
+
→ Append to CLAUDE.md > Critical Conventions
+
+
- **Design for extensibility before adding items**: When building infrastructure that will have + things added to it (menus, config schemas, API surfaces), build the extensibility mechanism + first — conditional rendering, feature-flag gating, discovery. Retrofitting causes rework.
+
+
+ + + +
+
+ + +
+
+
+
Verify contracts and references, don't assume
+
+ → CLAUDE.md + PR #1325, PR #1329 +
+
+
+
PR #1325: hook used nonexistent $CLAUDE_TOOL_INPUT env var. PR #1329: script referenced old file path after directory restructuring — silently did nothing.
+
→ Append to CLAUDE.md > Critical Conventions
+
+
- **Verify contracts and references**: Before building on an assumption (env var exists, path is + correct, URL is reachable), verify the contract. After moving anything, grep scripts, workflows, + manifests, and configs — not just source code.
+
+
+ + + +
+
+ + +
+
+
+
CI/CD security and automation
+
+ → CLAUDE.md + PR #1310, PR #1334, PR #1331 +
+
+
+
PR #1310: pull_request_target granted write access to forked PRs. PR #1334: hardcoded bot token rotted, returned 401. PR #1331: auto-merge failed silently without repo setting.
+
→ Append to CLAUDE.md > Critical Conventions
+
+
- **CI/CD security**: Never use `pull_request_target` (grants write access to forked PR code). + Never hardcode tokens — use `actions/create-github-app-token`. For automated pipelines: + discovery → validation → PR → auto-merge.
+
+
+ + + +
+
+ + +
+
+
+
Full-stack awareness for cross-cutting changes
+
+ → CLAUDE.md + PR #1282, PR #1289 +
+
+
+
PR #1282: existing S3 seeding pipeline could be reused instead of inventing parallel upload. PR #1289: credential scoping required updating all consumers (backend, CLI, SDK, runner, sidecar) simultaneously.
+
→ Append to CLAUDE.md > Critical Conventions
+
+
- **Full-stack awareness**: Before building a new pipeline, check if an existing one can be + reused. Auth/credential/API changes must update ALL consumers (backend, CLI, SDK, runner, + sidecar) in the same PR.
+
+
+ + + +
+
+ + +
+
+
+
Separate configuration from code
+
+ → CLAUDE.md + PR #1337, general principle +
+
+
+
PR #1337: frontend hardcoded localhost:8000 instead of using env var — broke kind/prod deployments. Values that vary by environment must be externalized.
+
→ Append to CLAUDE.md > Critical Conventions
+
+
- **Separate configuration from code**: Config changes must not require code changes. Externalize + via env vars, ConfigMaps, manifests, or feature flags. If a value varies across environments + or changes over time, it's config, not code.
+
+
+ + + +
+
+ + +

→ Component Guide (1 operator-specific guideline)

+ + +
+
+
+
Defensive Kubernetes patterns
+
+ → operator/DEVELOPMENT.md + PR #1290, PR #1299 +
+
+
+
PR #1290: deletecollection denied by RBAC, orphaned pods accumulated. PR #1299: operator OOMKilled at scale, needed resource limits + GOMEMLIMIT.
+
→ New section in components/operator/DEVELOPMENT.md
+
+
## Defensive Patterns + +- **Deletion fallback**: Try `deletecollection` first; if RBAC denies, fall back to list+delete. + Without this, orphaned pods accumulate silently. +- **Resource limits from day one**: Set requests/limits AND `GOMEMLIMIT` on Go controllers. + PR #1299 fixed OOMKills at scale. +- **Proxy propagation**: HTTP/HTTPS/NO_PROXY do NOT auto-propagate to spawned pods/sidecars. + Forward them explicitly in the reconciler. +- **Service URL parameterization**: In-cluster DNS differs from localhost. Use env vars with + per-overlay values, never hardcoded URLs.
+
+
+ + + +
+
+ + +

Also (infrastructure change)

+ +
+
+
+
Update Critical Conventions section description
+
+ → CLAUDE.md + Housekeeping +
+
+
+
→ Replace section description in CLAUDE.md > Critical Conventions
+
+
Current: +Rules that apply across ALL components. Per-component details live in component DEVELOPMENT.md files. + +Proposed: +Cross-cutting rules that apply across ALL components. Component-specific conventions live in +component DEVELOPMENT.md files (see [BOOKMARKS.md](BOOKMARKS.md) > Component Development Guides).
+
+
+ + + +
+
+ + +
+
+ 0 merge + 0 edit + 0 close + 7 pending +
+
Click buttons above to triage each item
+
+ + + + From cc45dcf5ef85604f2a953624bc055b249fa6b378 Mon Sep 17 00:00:00 2001 From: Ambient Code Bot Date: Thu, 16 Apr 2026 22:59:01 -0400 Subject: [PATCH 2/2] chore: remove triage dashboard from PR (local-only artifact) Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/knowledge-finder-triage.html | 318 ------------------------------ 1 file changed, 318 deletions(-) delete mode 100644 docs/knowledge-finder-triage.html diff --git a/docs/knowledge-finder-triage.html b/docs/knowledge-finder-triage.html deleted file mode 100644 index b40643aec..000000000 --- a/docs/knowledge-finder-triage.html +++ /dev/null @@ -1,318 +0,0 @@ - - - - - -Knowledge Finder — Post-v0.2.0 Triage - - - - -
-

Knowledge Finder — Post-v0.2.0 Triage

-

23 PRs analyzed since v0.2.0 (April 10–17, 2026). 6 consolidated guidelines extracted. Each shows its proposed destination based on impact radius.

-
-
5
→ CLAUDE.md
-
1
→ Component Guide
-
23
PRs Analyzed
-
-
- -
- Triage checklist — for each item, ask: -
    -
  1. Is it cross-cutting enough for its proposed destination?
    2. -
  2. Would an agent knowing this have avoided the rework described?
    3. -
  3. Is the wording concise and actionable?
    4. -
  4. Does it duplicate anything already in Critical Conventions?
    5. -
-
- - -

→ CLAUDE.md Critical Conventions (5 cross-cutting guidelines)

- - -
-
-
-
Design for extensibility before adding items
-
- → CLAUDE.md - PR #1333 → #1326 -
-
-
-
PR #1333 built menu infrastructure with unconditional separator. PR #1326 had to rework it to make separators conditional and feature-flag-gated.
-
→ Append to CLAUDE.md > Critical Conventions
-
-
- **Design for extensibility before adding items**: When building infrastructure that will have - things added to it (menus, config schemas, API surfaces), build the extensibility mechanism - first — conditional rendering, feature-flag gating, discovery. Retrofitting causes rework.
-
-
- - - -
-
- - -
-
-
-
Verify contracts and references, don't assume
-
- → CLAUDE.md - PR #1325, PR #1329 -
-
-
-
PR #1325: hook used nonexistent $CLAUDE_TOOL_INPUT env var. PR #1329: script referenced old file path after directory restructuring — silently did nothing.
-
→ Append to CLAUDE.md > Critical Conventions
-
-
- **Verify contracts and references**: Before building on an assumption (env var exists, path is - correct, URL is reachable), verify the contract. After moving anything, grep scripts, workflows, - manifests, and configs — not just source code.
-
-
- - - -
-
- - -
-
-
-
CI/CD security and automation
-
- → CLAUDE.md - PR #1310, PR #1334, PR #1331 -
-
-
-
PR #1310: pull_request_target granted write access to forked PRs. PR #1334: hardcoded bot token rotted, returned 401. PR #1331: auto-merge failed silently without repo setting.
-
→ Append to CLAUDE.md > Critical Conventions
-
-
- **CI/CD security**: Never use `pull_request_target` (grants write access to forked PR code). - Never hardcode tokens — use `actions/create-github-app-token`. For automated pipelines: - discovery → validation → PR → auto-merge.
-
-
- - - -
-
- - -
-
-
-
Full-stack awareness for cross-cutting changes
-
- → CLAUDE.md - PR #1282, PR #1289 -
-
-
-
PR #1282: existing S3 seeding pipeline could be reused instead of inventing parallel upload. PR #1289: credential scoping required updating all consumers (backend, CLI, SDK, runner, sidecar) simultaneously.
-
→ Append to CLAUDE.md > Critical Conventions
-
-
- **Full-stack awareness**: Before building a new pipeline, check if an existing one can be - reused. Auth/credential/API changes must update ALL consumers (backend, CLI, SDK, runner, - sidecar) in the same PR.
-
-
- - - -
-
- - -
-
-
-
Separate configuration from code
-
- → CLAUDE.md - PR #1337, general principle -
-
-
-
PR #1337: frontend hardcoded localhost:8000 instead of using env var — broke kind/prod deployments. Values that vary by environment must be externalized.
-
→ Append to CLAUDE.md > Critical Conventions
-
-
- **Separate configuration from code**: Config changes must not require code changes. Externalize - via env vars, ConfigMaps, manifests, or feature flags. If a value varies across environments - or changes over time, it's config, not code.
-
-
- - - -
-
- - -

→ Component Guide (1 operator-specific guideline)

- - -
-
-
-
Defensive Kubernetes patterns
-
- → operator/DEVELOPMENT.md - PR #1290, PR #1299 -
-
-
-
PR #1290: deletecollection denied by RBAC, orphaned pods accumulated. PR #1299: operator OOMKilled at scale, needed resource limits + GOMEMLIMIT.
-
→ New section in components/operator/DEVELOPMENT.md
-
-
## Defensive Patterns - -- **Deletion fallback**: Try `deletecollection` first; if RBAC denies, fall back to list+delete. - Without this, orphaned pods accumulate silently. -- **Resource limits from day one**: Set requests/limits AND `GOMEMLIMIT` on Go controllers. - PR #1299 fixed OOMKills at scale. -- **Proxy propagation**: HTTP/HTTPS/NO_PROXY do NOT auto-propagate to spawned pods/sidecars. - Forward them explicitly in the reconciler. -- **Service URL parameterization**: In-cluster DNS differs from localhost. Use env vars with - per-overlay values, never hardcoded URLs.
-
-
- - - -
-
- - -

Also (infrastructure change)

- -
-
-
-
Update Critical Conventions section description
-
- → CLAUDE.md - Housekeeping -
-
-
-
→ Replace section description in CLAUDE.md > Critical Conventions
-
-
Current: -Rules that apply across ALL components. Per-component details live in component DEVELOPMENT.md files. - -Proposed: -Cross-cutting rules that apply across ALL components. Component-specific conventions live in -component DEVELOPMENT.md files (see [BOOKMARKS.md](BOOKMARKS.md) > Component Development Guides).
-
-
- - - -
-
- - -
-
- 0 merge - 0 edit - 0 close - 7 pending -
-
Click buttons above to triage each item
-
- - - -