chore(claude): rework rules and add notes policy

claude/CLAUDE.md

@@ -4,28 +4,24 @@
 - for plans, reports, design docs, and anything benefiting from diagrams, styling, or embedded images, prefer HTML over Markdown
 - for conventional files (README, CONTRIBUTING, LICENSE, CHANGELOG, etc.) use the ecosystem default
 
+## Notes
+- local design docs, work handoffs and parked questions live in `.notes/` per project (see ~/.config/claude/rules/notes.md)
+
 ## Diagnostics
-- IMPORTANT: pursue root cause before proposing a fix; never propose a manual workaround before identifying the underlying cause
+- IMPORTANT: find the root cause before proposing a fix; never present a workaround as a fix (see ~/.config/claude/rules/diagnostics.md)
-- if a fix doesn't resolve the symptom, dig deeper instead of layering patches
+- if a fix doesn't resolve the symptom, revisit the cause instead of layering patches
-- verify the fix addresses the reported behavior, not just that the error went away
-- for system/boot/network/regression bugs, write a root-cause hypothesis first (see ~/.config/claude/rules/diagnostics.md)
 
 ## Trust & verification
 - IMPORTANT: don't present plausible-sounding details as facts; verify file paths, flags, function and library behavior by reading code or docs first
 - when a claim depends on external behavior (library APIs, system semantics, game mechanics, etc.), cite the source you verified against, or mark it as unverified
 
 ## Planning vs execution
-- IMPORTANT: when asked to "plan", "analyze", "deep-dive", or "research", produce documents only; no Edit/Write (except to the plan file) or Bash mutations until approved
+- IMPORTANT: when asked to "plan", "analyze", "deep-dive", or "research", produce documents only; no Edit/Write (except to the plan file or `.notes/`) or Bash mutations until approved
 - if a request is ambiguous between planning and implementing, ask which one
 
 ## Scope
-- if a diff grows beyond the original request, stop and confirm before continuing
+- don't start unrelated work on your own; if a diff grows beyond the request, stop and confirm
-
+- in orchestrated work (the `matej` skill), an agent working from a brief stays inside the brief instead: it notes anything outside it as a leftover and keeps going
-## Workflow
-- when redirected or interrupted, stop the current approach immediately and follow the new direction without explaining or defending it
-- focus on one goal per session; don't drift into unrelated improvements
-- implement changes directly; don't use sub-agents/Task for simple operations like renames, file moves, or single-file edits
-- use Task agents only for genuinely complex parallel exploration or research, not for straightforward implementation
 
 ## Comments
 - lowercase, no trailing punctuation
@@ -35,5 +31,9 @@
 - keyword comments must always include the `(@janezicmatej)` attribution
 
 ## Git
-- agents MUST commit with `--no-gpg-sign`
+- agents never sign commits, in any form: they are not me. commit with `--no-gpg-sign`; I re-sign branches on my host (`git sign-branch`) before they are pushed
-- when implementing multi-step work, split into logical commits the user can review and stage independently; don't bundle everything into one
+- use the identity git already has; where it has none, commit as `-c user.name=agent -c user.email=agent@sandbox.invalid` (my host signing resets the author)
+- commit messages: a conventional-commit subject line of at most 72 characters including the prefix; a body only where the project wants one, wrapped at 72; no trailers
+- stage paths explicitly; never `git add .` or `git add -A`
+- split multi-step work into a few logical commits I can review; condense fixups before handing a branch back
+- every branch, worktree and container you create is yours to remove when the work ends; never remove ones you did not create

claude/rules/diagnostics.md

@@ -1,26 +1,8 @@
 # Diagnostics rules
 
-Detailed root-cause discipline for system, boot, network, and regression bugs. The headline rules live in `CLAUDE.md`; this file is the long form.
+The long form of the headline rules in `CLAUDE.md`.
 
-## Root-cause hypothesis
+- Say what the cause is, with the evidence (file and line, log excerpt, command output), before proposing a fix. For system, boot, network and regression bugs, also say which other cause you ruled out and why.
-
+- A workaround is labelled as one, with what would have to change to make it unnecessary. Don't mask an error with a try/except, a retry or a flag without asking first.
-Before proposing any fix for a system/boot/network/regression bug, write a "Root cause hypothesis" section with these four parts:
+- If the fix doesn't resolve the symptom, go back to the cause; don't stack another patch on top.
-
+- Done means the reported behaviour is now right, checked by re-running what failed. An error that went away is not enough. If the fix touched a process, daemon or background job, check it left nothing behind (processes, sockets, locks, temp files).
-1. **Symptom** — the observable behavior, copied verbatim where possible (error message, missing output, wrong value)
-2. **Proximate cause** — the immediate trigger, with evidence (file path + line, log excerpt, command output)
-3. **Underlying cause** — why the proximate cause occurred; the layer of indirection that makes the proximate cause possible
-4. **Ruled-out alternative** — at least one other plausible hypothesis you considered and why you discarded it
-
-Only after writing all four parts should you propose a fix.
-
-## Workaround discipline
-
-- never present a manual workaround as a fix; if a workaround is the only option, label it explicitly as a workaround and describe what would need to change to make it unnecessary
-- if a fix doesn't resolve the symptom on first try, don't layer another patch; revisit the hypothesis instead
-- if you're tempted to add a try/except, retry loop, or feature flag to mask an error, stop and ask first
-
-## Verification
-
-- before declaring a fix done, re-run the failing check and confirm the reported behavior is now correct
-- "the error message disappeared" is not sufficient; confirm the underlying behavior matches what was expected
-- if the fix touches a process, daemon, or background job, confirm it cleaned up after itself (no orphaned procs, sockets, locks, temp files)

claude/rules/notes.md

@@ -0,0 +1,78 @@
+# Notes rules
+
+Each project keeps its local working notes in `.notes/` at the project root: design docs, work that spans sessions, and questions parked for later. The notes are never committed to the project. The `notes` skill does the mechanics (creating the dir, picking ids, close-out).
+
+## Layout
+
+```
+.notes/            # its own git repo, never pushed
+  README.md        # one line pointing here
+  index.html       # generated: the overview, links only
+  notes.css        # generated: copy of the skill's stylesheet every page uses
+  _pages/          # generated: questions, briefs and other markdown rendered to pages
+  _out/            # generated: other/out/ made self-contained, css inlined, for sending
+  docs/            # dNNN-slug.html, or dNNN-slug/index.html with its assets
+  work/            # wNNN-slug/ while in flight, removed at close-out
+  questions/       # qNNN-slug.md, removed when settled
+  other/
+    in/            # placed by the user
+    out/           # prepared for someone else
+```
+
+- created on first need (the first doc, work item or question in a project), not up front
+- the generated files are rebuilt by the skill's `notes.py` on every commit and never committed; browse every project's notes at once with `notes.py serve` (one port, roots `$NOTES_ROOTS`, else `~/git`), or one project with `python -m http.server -d .notes`
+- every page has a back link to the index; ids like `d007` or `q014` in markdown become links
+
+## Numbering
+
+- `<letter><NNN>-<slug>`: `d` docs, `w` work, `q` questions; each letter has its own counter, three digits, lowercase kebab slug
+- numbers are never reused, including numbers of deleted items: the next id is the highest ever used in that bucket (files plus `git -C .notes log --all --name-only`) + 1
+- refer to items by id everywhere: chat, other notes, commit subjects ("see q014", "per d007")
+- `other/` is not numbered
+
+## docs
+
+- point-in-time design docs: plans, proposals, research, reviews; html per the output format rules
+- one look for all docs: link `notes.css`, start `main.page` with `nav.back`, use only the components documented at the top of `notes.css`, no `<style>` or font links of their own; the skill shows the skeleton
+- a doc with assets becomes a folder: `dNNN-slug/index.html` plus its files, linked relatively
+- a status line sits directly under the title as `<p class="status current|stale|superseded">…</p>` (`notes.py` reads it): `status: current`, `status: partly stale (<what changed>, <date>)` or `status: superseded by dNNN (<date>)`, with `dNNN` a relative link to the newer doc
+- once done, a doc's body doesn't change; only its status line does. a new design gets a new doc
+
+## work
+
+- one folder per piece of work that spans sessions; a single-session task gets none
+- typical files: `brief.md` (goal, done when, scope, decisions to ask), `plan.html` (the proposal to approve), `report.md` (what was built, what differs, leftovers), plus research the work needed
+- close-out runs in the same session the work ends (branch merged or work dropped):
+  1. lasting design goes to `docs/`: a new doc, or a status line on an existing one
+  2. leftovers go to `questions/`, one each, with `origin: wNNN`
+  3. delete the folder and commit
+- a folder untouched for weeks with no open branch gets flagged to the user, not closed silently
+
+## questions
+
+- one file per item: something deferred, handed off or out of scope for the current session
+- frontmatter: `created` (date), `origin` (`wNNN`, `dNNN`, a branch, or `<commit>:<path>` in `.notes`), `status: open`
+- body: what is open, why it matters, what is known, where to look
+- before acting on one, check the repo for whether it still applies
+- settled: fold the outcome into a doc or a work item if it is worth keeping, delete the file, commit with a subject saying how it was settled
+
+## other
+
+- `in/`: read only when the user points at it
+- `out/`: written for a person, not for later sessions; don't treat it as context
+- html in `out/` uses the same `notes.css` and components as docs, without an id or status line; the copy that leaves is the generated self-contained one in `_out/`
+- `out/` holds documents and the few small files that go with them (a script, a config snippet); bulk output for a person (screenshot sets, builds, logs) does not go into `.notes/` at all: in a sandbox vm it goes to the host handoff mount once there is one, until then ask where
+
+## History
+
+- `.notes/` is its own git repo with no remote, its `.gitignore` holding the generated files; commit after each change set, subject line only, naming the ids touched (`q014: settled by a3f4573`)
+- git history replaces archives: delete instead of moving to an archive folder, rewrite instead of keeping dated copies
+- never stage `.notes/` from the project repo: stage project paths explicitly, never `git add .` or `git add -A` there
+- the host's global gitignore hides `.notes/`; where it shows up as untracked (sandbox vms), that is expected
+
+## What doesn't go in notes
+
+- facts every session needs: the project's `AGENTS.md`/`CLAUDE.md`, or memory when they are personal
+- anything teammates need: the project repo
+- secrets
+- committed project files never reference `.notes/` paths