From 34c32ba64aa1de36095d3b84512624aaf5d625fa Mon Sep 17 00:00:00 2001 From: Myx Date: Wed, 22 Jul 2026 21:25:39 +0200 Subject: [PATCH] chore: cheap named-bug path and prefer lint:fix Wire fix-bug prompts to a single Obsidian note plus default scope, and require npm run lint:fix instead of hand-fixing auto-fixable lint/format. Co-authored-by: Cursor --- AGENTS.md | 11 +++-- agents-docs/AGENT_WORKFLOW.md | 1 + agents-docs/BUG_TRACKER.md | 79 +++++++++++------------------------ agents-docs/ENGINEERING.md | 16 +++---- agents-docs/LESSONS-INDEX.md | 3 +- agents-docs/LESSONS.md | 19 ++++++--- 6 files changed, 56 insertions(+), 73 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 54a1dc7..23ac8b5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,10 @@ Agents **cannot** open a new Cursor chat. To reset context: **At session start:** if `agents-docs/HANDOFF.md` has `Status: active`, read it first and continue Next steps. Do not redo Completed work. +## Named Obsidian bugs + +When the user says `fix bug "…"`, follow `agents-docs/BUG_TRACKER.md` § Named fix: open **that one** vault note under `Log/Bugs/`, use it as acceptance criteria, fix in default scope, then set `status: Resolved`. Do not scan the whole bug inbox. + ## Default work scope (token fence) Unless the user **explicitly** expands scope, stay inside: @@ -76,8 +80,9 @@ Skip full red-green for docs/copy/agent text, formatting, trivial wiring already ### Lint / type correctness (scoped) 1. Targeted Vitest under `toju-app/` (and colocated Electron specs only if you changed those files). -2. `npm run lint` — fix errors; do not paste entire lint logs into the chat. -3. `npm run build` when client types/templates could break; `npm run build:electron` only if you changed Electron sources. +2. Auto-fix style first: `npm run lint:fix` from repo root (`format` + `sort:props` + `eslint . --fix`). Do **not** hand-edit formatting/import-sort/eslint-fixable issues — re-run `lint:fix`. Then confirm clean with `npm run lint` only if you need a no-write check; prefer trusting `lint:fix` exit 0. +3. Do not paste entire lint logs into the chat — fix via `lint:fix` / minimal code changes for non-auto issues. +4. `npm run build` when client types/templates could break; `npm run build:electron` only if you changed Electron sources. Do **not** run `cd server && npm run build` or `npm run test:e2e` unless scope expanded or the bug is proven there. @@ -91,7 +96,7 @@ IPC/preload/WS contract changes → `agents-docs/features/.md` when that c - [ ] Asked behavior proven (not only unit tests green) - [ ] Stayed in scope (`toju-app` + targeted `electron` + CI) unless user expanded it - [ ] Appropriate targeted tests for logic changes -- [ ] Lint/build only for touched packages +- [ ] Lint via `npm run lint:fix` (not hand-fixed style); build only touched packages - [ ] Docs only if contracts changed - [ ] Lesson + index entry if corrected this session - [ ] If the thread is long and work remains: write `HANDOFF.md` and ask user for a new chat diff --git a/agents-docs/AGENT_WORKFLOW.md b/agents-docs/AGENT_WORKFLOW.md index 69139ad..419fbb4 100644 --- a/agents-docs/AGENT_WORKFLOW.md +++ b/agents-docs/AGENT_WORKFLOW.md @@ -8,6 +8,7 @@ These rules apply to **all AI agents** working on this project. - Electron: follow the renderer → preload → one handler path; never dump the whole `electron/` tree. - Prefer path-scoped search; one focused agent; no Bugbot / security / best-of-N unless asked. - **Handoff > fat chats:** agents cannot open new chats. Write `agents-docs/HANDOFF.md` and ask the user to start a new chat with that file attached. +- **Named bugs:** `fix bug "…"` → one Obsidian note (`BUG_TRACKER.md` § Named fix), then default repo scope — not the whole vault or monorepo. - **Models:** keep the user’s latest problem-solving model. Cut cost with scope + handoffs, not weaker models. Do **not** re-read this whole file every turn after the first skim. diff --git a/agents-docs/BUG_TRACKER.md b/agents-docs/BUG_TRACKER.md index cff9e26..e218df4 100644 --- a/agents-docs/BUG_TRACKER.md +++ b/agents-docs/BUG_TRACKER.md @@ -1,49 +1,48 @@ # Obsidian Bug Tracker — Agent Contract -User-maintained bug reports live outside the repo. Read this file when asked to triage, investigate, or work from the bug backlog. +User-maintained bug reports live outside the repo. Use this when the user names a bug or asks to triage the backlog. -**Overrides** `agents-docs/AGENT_WORKFLOW.md` §8 (Autonomous Bug Fixing) unless the user explicitly asks you to fix a bug in code. +**Inbox:** `/home/ludde/Nextcloud/Obsidian Vault/Log/Bugs/` +**Attachments:** `…/Bugs/attachments//` +**Dashboard / template:** `…/Log/Create bug.md`, `…/Log/Templates/Bug Report.md` --- -## Location +## Named fix (default — cheap path) -| Item | Path | -|------|------| -| Bug inbox | `/home/ludde/Nextcloud/Obsidian Vault/Log/Bugs/` | -| Attachments | `…/Bugs/attachments//` | -| Dashboard | `/home/ludde/Nextcloud/Obsidian Vault/Log/Create bug.md` | -| Template | `/home/ludde/Nextcloud/Obsidian Vault/Log/Templates/Bug Report.md` | +When the user says e.g. `fix bug "Images and files in chat doesn't load"`: + +1. **Resolve one note** under `Log/Bugs/` whose title matches (usually `Bug - .md`). Do not list or read the whole inbox. +2. **Read that note** (Description, Steps, Expected/Actual, Logs). Read attachments only under that bug’s attachment folder if referenced. +3. Acceptance criteria = the note’s Expected Result (plus any clarifying line from the user). +4. **Fix in default repo scope** (`toju-app/` + targeted `electron/` + CI) per `AGENTS.md`. Do not crawl `server/` / `e2e/` / other packages unless the note or user clearly requires it — then ask once. +5. Prove the asked behavior (not only unit-green). Prefer a regression that encodes the note’s failure mode. +6. When done: set that note’s frontmatter `status` to `Resolved` (or `Closed` if the user prefers). Do not rewrite Description / Investigation / Resolution unless asked. +7. Long thread + more work left → write `agents-docs/HANDOFF.md` and ask for a new chat. + +Do **not** re-read `BUG_TRACKER.md` every turn after the first use. Do **not** load the stale “open bugs” snapshot as truth — the vault files are source of truth. --- -## Allowed actions on vault files +## Backlog triage only -Unless the user explicitly asks for more: - -1. **Change `status`** in a bug note's YAML frontmatter (`Open` → `Resolved` or `Closed`). -2. **Move files** (e.g. reorganize notes or attachments when instructed). - -Do **not** edit other vault fields or sections (`Investigation`, `Resolution`, description, etc.) unless the user asks. +If the user asks to list/triage open bugs (not a named fix): `ls` / glob `Log/Bugs/*.md`, filter `status: Open`, summarize titles — still don’t open every body until they pick one. --- -## Allowed reads (unrestricted) +## Vault edit policy -To understand and solve bugs you may read freely: +Unless the user asks for more: -- All bug notes and attachments under `Log/Bugs/` -- The full MetoYou repo (code, tests, logs, docs) -- Runtime output, test results, and debug artifacts +- **Allowed write:** frontmatter `status` (`Open` → `Resolved` / `Closed`); move files if they specify a convention. +- **Do not edit:** other frontmatter fields, Description, Steps, Investigation, Resolution, etc. -Investigation findings belong in chat or in repo changes — not in the vault — unless the user asks you to update the note. +Investigation findings go in chat or the repo — not the vault — unless asked. --- ## Bug note format -Each note is Markdown with YAML frontmatter: - ```yaml --- title: Bug - … @@ -57,34 +56,4 @@ tags: [bug] --- ``` -Body sections: **Description**, **Steps to Reproduce**, **Expected Result**, **Actual Result**, **Logs / Screenshots**, **Investigation**, **Resolution**. - -The dashboard (`Create bug.md`) uses Dataview; keep `type: bug` and `status` accurate so counts stay correct. - ---- - -## Workflow - -1. List open bugs: `Glob` or `ls` on `…/Log/Bugs/*.md`, filter `status: Open`. -2. Read the note and any linked attachments. -3. Investigate in the repo (read-only toward the vault). -4. Report findings to the user. -5. Only when told to fix: implement in repo (TDD, lint, build per `AGENTS.md`). -6. When a bug is done: update vault `status` to `Resolved` or `Closed` (and move files if the user specifies a convention). - ---- - -## Open bugs (snapshot 2026-06-10) - -| Title | Priority | Environment | -|-------|----------|-------------| -| Attachments gets syncronized corrupt | Critical | All major clients | -| Chats doesn't sync for multi client users | High | All | -| No android app icon | High | Android | -| No login screen mobile phone on startup | High | Android, Android Browser | -| Fresh users have the server list in dashboard completely empty until anything searched | High | — | -| Video attachment on android gets sent in the message bubble above with no preview image | High | Android | -| Local files should be remembered by client | High | — | -| Emojis should be user bound not client bound | Medium | All | - -Re-scan the folder at session start; this table is not auto-updated. +Body: **Description**, **Steps to Reproduce**, **Expected Result**, **Actual Result**, **Logs / Screenshots**, **Investigation**, **Resolution**. diff --git a/agents-docs/ENGINEERING.md b/agents-docs/ENGINEERING.md index 3600d78..8a14fb8 100644 --- a/agents-docs/ENGINEERING.md +++ b/agents-docs/ENGINEERING.md @@ -196,8 +196,8 @@ cd server && npm run build # server tsc npm run build:all # all of the above # --- lint / format --- -npm run lint # eslint . -npm run lint:fix # format + sort:props + eslint --fix +npm run lint # eslint . (check only) +npm run lint:fix # preferred: format + sort:props + eslint --fix npm run format # prettier on Angular HTML templates only npm run format:check # prettier --check on HTML templates @@ -214,16 +214,16 @@ npm run migration:revert # roll back last Before marking work complete: -- [ ] Tests written before implementation -- [ ] All tests passing (`npm run test`, plus `npm run test:e2e` if behavior is user-visible) -- [ ] `npm run lint` passes -- [ ] Affected package builds: `npm run build` / `npm run build:electron` / `cd server && npm run build` +- [ ] Tests written before implementation (balanced — see `/AGENTS.md`) +- [ ] Asked behavior proven; targeted tests pass (`npm run test:e2e` only if in scope / user-visible and needed) +- [ ] `npm run lint:fix` passes (do not hand-fix auto-fixable lint/format) +- [ ] Affected package builds: `npm run build` / `npm run build:electron` when those packages were touched - [ ] Naming conventions followed - [ ] Errors handled - [ ] Security considered (no secrets in code, no plaintext token logging, no IPC handler accepting arbitrary file paths) - [ ] Feature docs updated if contract/schema/invariant changed (see `agents-docs/AGENTS_FEATURES.md`) - [ ] `CONTEXT.md` updated if a domain term was resolved or introduced (see `agents-docs/AGENTS_CONTEXT.md`) - [ ] ADR written if a hard-to-reverse decision was made (see `agents-docs/AGENTS_ADRS.md`) -- [ ] Lesson recorded in `agents-docs/LESSONS.md` if this session produced a correction, revert, or hidden constraint (see triggers in `agents-docs/AGENT_WORKFLOW.md`) -- [ ] PR opened with summary and linked issues +- [ ] Lesson recorded in `agents-docs/LESSONS.md` + `LESSONS-INDEX.md` if this session produced a correction +- [ ] PR opened with summary and linked issues when requesting merge - [ ] Gitea Workflows checks passing diff --git a/agents-docs/LESSONS-INDEX.md b/agents-docs/LESSONS-INDEX.md index 2577290..6add931 100644 --- a/agents-docs/LESSONS-INDEX.md +++ b/agents-docs/LESSONS-INDEX.md @@ -9,7 +9,7 @@ Tags help grepping: `rg '\\[attachments\\]' agents-docs/LESSONS-INDEX.md` ## Index - Keep `NgOptimizedImage` off runtime blob and data URLs — `[angular] [images]` -- Read the exact Obsidian bug note before diagnosing a named ticket — `[workflow] [bugs]` +- Read the exact Obsidian bug note for `fix bug "…"` (one note only) — `[workflow] [bugs]` - Run `npm run i18n:sync` after editing any `public/i18n/catalog/*.json` file — `[i18n] [testing]` - Match direct-call recipients against every local identity alias, exactly like DMs already do — `[direct-call] [identity]` - Resolve outbound direct-call recipient ids to the peer's connected signal identity — `[direct-call] [identity] [signaling]` @@ -49,6 +49,7 @@ Tags help grepping: `rg '\\[attachments\\]' agents-docs/LESSONS-INDEX.md` - Use terminal Vitest when the test tool hangs — `[testing]` - Do not add fake chrome around screenshots — `[website] [design]` - Verify lint exits 0 before claiming done — `[verification]` +- Prefer `npm run lint:fix` over hand-fixing lint/format — `[verification] [lint] [tokens]` - Use blob URLs for inline attachment previews — `[attachments] [electron]` - Resolve Electron drag-and-drop file paths with webUtils — `[attachments] [electron]` - Preserve uploader local attachment paths across sync — `[attachments] [persistence]` diff --git a/agents-docs/LESSONS.md b/agents-docs/LESSONS.md index 8105912..5437fcb 100644 --- a/agents-docs/LESSONS.md +++ b/agents-docs/LESSONS.md @@ -55,10 +55,10 @@ Durable rules for AI agents working on this project. ### Read the exact Obsidian bug note before diagnosing a named ticket [workflow] [bugs] -- **Trigger:** The user names a `Bug - …` ticket, but the worktree already contains plausible changes or a similarly named resolved ticket. -- **Rule:** Resolve the exact note under `Log/Bugs/`, read every reported variant and reproduction step, and only then decide which code changes and status update belong to that ticket. -- **Why:** attachment reload-host changes looked related to “Images and files in chat doesn't load” but came from a separate resolved ticket and did not cover the reported channel-switch state regression. -- **Example:** read `/home/ludde/Nextcloud/Obsidian Vault/Log/Bugs/Bug - Images and files in chat doesn't load.md` before implementing or committing its fix. +- **Trigger:** The user says `fix bug "…"`, names a `Bug - …` ticket, or the worktree already contains plausible changes / a similarly named resolved ticket. +- **Rule:** Resolve and read **only** that note under `Log/Bugs/` (and its attachment folder if needed); use Expected Result as acceptance; fix in default scope; do not list the whole inbox or treat `BUG_TRACKER.md`'s snapshot table as live. +- **Why:** attachment reload-host changes looked related to “Images and files in chat doesn't load” but came from a separate resolved ticket and did not cover the reported channel-switch state regression; inbox-wide reads also burn tokens for no gain. +- **Example:** `fix bug "Images and files in chat doesn't load"` → read `/home/ludde/Nextcloud/Obsidian Vault/Log/Bugs/Bug - Images and files in chat doesn't load.md` only, then implement against its Steps/Expected. ### Run `npm run i18n:sync` after editing any `public/i18n/catalog/*.json` file [i18n] [testing] @@ -326,12 +326,19 @@ Durable rules for AI agents working on this project. - **Why:** duplicated chrome makes CTA/product previews look broken, and bottom-aligned large headings can cover accompanying text on the marketing site. - **Example:** `website/src/app/pages/home/home.component.html` should render the screenshot directly; `host-section` should use top-aligned heading and `.host-section-copy` columns. +### Prefer `npm run lint:fix` over hand-fixing lint/format [verification] [lint] [tokens] + +- **Trigger:** about to manually re-indent, reorder imports, or tweak Prettier/ESLint-fixable style after seeing lint failures. +- **Rule:** from repo root run `npm run lint:fix` (`format` + `sort:props` + `eslint . --fix`); only hand-edit remaining non-fixable errors. +- **Why:** manual style fixes burn turns and tokens and often miss what the project script already auto-corrects. +- **Example:** after code changes → `npm run lint:fix` → if exit 0, do not also rewrite imports by hand. + ### Verify lint exits 0 before claiming done [verification] - **Trigger:** about to report a task as complete after running tests but skipping ESLint. -- **Rule:** run `npm run lint` from the repo root and confirm exit code 0 before any "done" claim. +- **Rule:** run `npm run lint:fix` from the repo root (or `npm run lint` after fixes) and confirm exit code 0 before any "done" claim. - **Why:** `npm run test` only runs the toju-app Vitest suite — it doesn't cover the server, Electron, or website packages. ESLint (flat config in `eslint.config.js`) is the universal check across every package; type-style violations slip through tests and break Gitea Workflows for the next agent. -- **Example:** `npm run lint && echo OK` — only claim done after seeing `OK`. For Electron type errors specifically, also confirm `npm run build:electron` succeeds (it invokes `tsc -p tsconfig.electron.json`). +- **Example:** `npm run lint:fix && echo OK` — only claim done after seeing `OK`. For Electron type errors specifically, also confirm `npm run build:electron` succeeds (it invokes `tsc -p tsconfig.electron.json`). ### Use blob URLs for inline attachment previews [attachments] [electron]