From 7916e5e073b5165864bded9a8511bf559929476d Mon Sep 17 00:00:00 2001 From: Andrey Antukh Date: Wed, 18 Nov 2026 19:12:59 +0000 Subject: [PATCH] :books: Clarify agent memory guidance Promote Clojure design rules to a required core memory and simplify the discovery guide. Correct test output redirection and RPC routes. AI-assisted-by: gpt-6.1-terra --- .serena/memories/backend/core.md | 2 +- .../clojure/{design-rules.md => core.md} | 4 ++-- .serena/memories/clojure/idioms.md | 2 +- .serena/memories/critical-info.md | 3 +-- .serena/memories/testing.md | 4 ++-- AGENTS.md | 20 ++++++------------- 6 files changed, 13 insertions(+), 22 deletions(-) rename .serena/memories/clojure/{design-rules.md => core.md} (93%) diff --git a/.serena/memories/backend/core.md b/.serena/memories/backend/core.md index de55cfa1de..0a066d89cf 100644 --- a/.serena/memories/backend/core.md +++ b/.serena/memories/backend/core.md @@ -14,7 +14,7 @@ Backend: JVM Clojure; Integrant; PostgreSQL; Redis/Valkey; RPC; HTTP; storage; m ## Stable namespace map -- `app.rpc.commands.*`: RPC command implementations exposed under `/api/rpc/command/`. +- `app.rpc.commands.*`: RPC command implementations exposed under `/api/main/methods/`; `/api/rpc/command/` remains as a backward-compatible route. - `app.rpc.permissions`: permission predicate/check helper factories. - `app.http.*`: HTTP routes and middleware. - `app.auth.*`: provider-specific authentication helpers such as LDAP/OIDC. diff --git a/.serena/memories/clojure/design-rules.md b/.serena/memories/clojure/core.md similarity index 93% rename from .serena/memories/clojure/design-rules.md rename to .serena/memories/clojure/core.md index 2b439ee038..203ae823b3 100644 --- a/.serena/memories/clojure/design-rules.md +++ b/.serena/memories/clojure/core.md @@ -1,4 +1,4 @@ -# Clojure Design Rules +# Clojure Core How to shape a function in this codebase. Each rule came from a review round; do not re-derive from taste. @@ -11,4 +11,4 @@ How to shape a function in this codebase. Each rule came from a review round; do Reference implementation: the http metrics samplers in `app.http` (`sample-worker-metrics` / `sample-connector-metrics` are guard-free; `sample-http-metrics` guards at the boundary). -See also: `mem:clojure/idioms` (language behaviors), `mem:testing` (TDD and test conventions). +See also: `mem:clojure/idioms` (language behaviors and naming exceptions), `mem:clojure/logging` (structured logging), `mem:testing` (TDD and test conventions). diff --git a/.serena/memories/clojure/idioms.md b/.serena/memories/clojure/idioms.md index cf85848c3a..e901805542 100644 --- a/.serena/memories/clojure/idioms.md +++ b/.serena/memories/clojure/idioms.md @@ -8,5 +8,5 @@ Behaviors confirmed against the language/stdlib — do not re-derive from assump - The analyzer reads `:async` only from the fn name meta and the `fn` operator meta; list-level meta is ignored (would make a MetaFn). `(fn ^:async [] …)` puts the meta on argv (pre/post only, NOT async). - Valid: `(defn ^:async f)`, `(defn- ^:async f)`, `(^:async fn [] …)` (the latter is what stock `t/async` generates itself). - `^:async` fns never throw synchronously (rejected promises instead); `try/catch/finally` supported; continuations are microtasks, timers and RxJS schedulers are macrotasks (FIFO). -- `!` suffix allowed cases (only exceptions to the no-new-`!` rule in `mem:clojure/design-rules`): mutating public `app.db` API (`insert!`, `update!`, `delete!`, `run!`, `tx-run!`, `exec!`, ...) and fns whose contract is to work over transients (stdlib `conj!`, `assoc!`, `dissoc!`, `disj!`, `persistent!` and custom helpers over them); any further case must be registered here with justification before use. +- `!` suffix allowed cases (only exceptions to the no-new-`!` rule in `mem:clojure/core`): mutating public `app.db` API (`insert!`, `update!`, `delete!`, `run!`, `tx-run!`, `exec!`, ...) and fns whose contract is to work over transients (stdlib `conj!`, `assoc!`, `dissoc!`, `disj!`, `persistent!` and custom helpers over them); any further case must be registered here with justification before use. - `cuerdas.core/index-of` returns `nil` (not `-1`) when the substring is absent, like `clojure.string/index-of`. `(pos? nil)` **throws on the JVM** but evaluates to `false` in CLJS (JS coercion), so `(if (pos? (str/index-of s "\n")) …)` works in the browser and crashes the backend. Guard with `some?` before `pos?` (this was `app.common.exceptions/first-line`). diff --git a/.serena/memories/critical-info.md b/.serena/memories/critical-info.md index ac15e674bd..15b1fc04cb 100644 --- a/.serena/memories/critical-info.md +++ b/.serena/memories/critical-info.md @@ -8,7 +8,7 @@ You are working on the GitHub project `penpot/penpot`, a monorepo. - Cross-cutting testing principles, TDD workflow, and anti-patterns: `mem:testing`. - Structured logging conventions (`:hint` casing and fields, log levels): `mem:clojure/logging` — read before adding or changing any log call. - Verified Clojure language behaviors that contradict common assumptions (e.g. `int?` covers `Long`; `integer?` is the general predicate): `mem:clojure/idioms` — read before assuming stdlib predicate semantics. -- Read `mem:clojure/design-rules` (function shape, boundary checks, naming) before writing or modifying Clojure/ClojureScript code — not only when designing a solution or an API. +- Read `mem:clojure/core` (function shape, boundary checks, naming) before writing or modifying Clojure/ClojureScript code — not only when designing a solution or an API. # Development workflow @@ -23,7 +23,6 @@ You are working on the GitHub project `penpot/penpot`, a monorepo. - **Never `git push`, force-push, or modify `git origin`** (or any other remote). The user pushes from their own shell; if a push is required, say so and wait. Never amend a commit that the user has already pushed unless explicitly asked. - **Never edit `CHANGES.md` by hand.** The changelog is generated from GitHub milestones during the release process; update it only via `mem:workflow/updating-changelog` (the `update-changelog` skill flow) or on explicit user request. - You have access to the GitHub CLI `gh` or corresponding MCP tools. -- Issues are also managed on Taiga. Read issues using the `read_taiga_issue` tool. - Before writing code, analyze the task in depth and describe your plan. If the task is complex, break it down into atomic steps. After making changes, run the applicable lint and format checks for the affected module before considering the work done (per example `mem:backend/core` or `mem:frontend/core`). - Align `let` binding values: when a `let` form has multiple bindings spanning several lines, align the value forms to the same column with spaces. - If you introduce delimiter errors (mismatched parens/brackets) in Clojure/CLJS files, fix them with `scripts/paren-repair` BEFORE running lint/format checks. See `mem:scripts/paren-repair` for usage. diff --git a/.serena/memories/testing.md b/.serena/memories/testing.md index ce301ff5bb..9112a05369 100644 --- a/.serena/memories/testing.md +++ b/.serena/memories/testing.md @@ -142,10 +142,10 @@ E2E tests should not be added unless explicitly requested. When running ANY test command (CLJS/JS or JVM): 1. **NEVER pipe test output directly to `| head`, `| tail`, `| grep`, or similar filters** — this can hide failures and cause you to miss critical errors. -2. **ALWAYS pipe to a file first, then read the file:** +2. **ALWAYS redirect to a file first, then read the file:** ```bash # CORRECT: - pnpm run test 2>&1 > /tmp/test-output.txt + pnpm run test > /tmp/test-output.txt 2>&1 grep -A 5 "failures" /tmp/test-output.txt # WRONG: diff --git a/AGENTS.md b/AGENTS.md index c39c02dcaf..c80c764bf4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,6 +39,8 @@ Do this **before planning, before coding, before touching any file**: 3. Read each affected module's **core memory** — the name is `/core` (e.g. `frontend/core`, `backend/core`, `common/core`). 4. If the core memory references deeper `mem:` memories relevant to your task, read those too. +5. Before writing or modifying Clojure or ClojureScript, read `mem:clojure/core` + and the relevant focused Clojure memories it references. **STOP: Do not proceed until you have read the core memory of every affected module.** Skipping this step is the #1 cause of incorrect or incomplete work. @@ -80,11 +82,6 @@ Review every prose output against these rules before delivering. Memories are the **primary project guidance** — not docs or readme files. They are dense, agent-oriented notes: terse bullets, invariants, no prose. -## Entry point - -Start at `critical-info` (the graph root). It describes the project structure, -module dependency graph, and references section-level core memories. - ## Progressive discovery model Memories form a **reference graph**, not a flat list: @@ -96,11 +93,8 @@ critical-info ← read first (graph root) └─ ... ← deeper memories as needed ``` -When working on a task: -1. Read `critical-info` to identify which sections are affected. -2. Read the affected section's `core` memory for an overview. -3. Follow `mem:` references in the core memory to focused memories relevant to your task. -4. Continue following references deeper as needed. +Follow the mandatory reading sequence above. Cross-cutting topics can also be +referenced directly from `critical-info` or other memories. ## Accessing memories @@ -117,9 +111,8 @@ When you encounter a `mem:` reference relevant to your task, read that memory ne ## Topic/folder organization -Memories are grouped into folders that mirror project modules or topics: -`backend/`, `common/`, `frontend/`, `render-wasm/`, `exporter/`, `workflow/`, etc. -Each folder's top-level memory is `/core`. +Memories are grouped into folders for modules or topics. Project modules have +a `/core` memory; other topic folders may contain focused memories only. --- @@ -155,4 +148,3 @@ precision while maintaining a strong focus on maintainability and performance. - `scripts/check-fmt-clj` — Check Clojure formatting without modifying files. - `scripts/ci` — CI orchestration script for running lint, tests, format checks and, on request (`--build`), production builds across modules. See `mem:scripts/ci`. - `scripts/gh.py` — Multi-purpose GitHub CLI helper. Subcommands: `issues` (list issues in a milestone), `prs` (fetch PR details), `advisories` (list/inspect security advisories). See `python3 scripts/gh.py --help`. -