git:20260812.ccabd9c to git:20260818.67333f7

- - prints `main` → you are in the **main worktree**. **Stop.** Run

- `git worktree add /tmp/librefang-<feature> -b <feature-branch> origin/main`

- and continue all work from that path.

- - prints `linked` → you are in a **linked worktree**. Continue.

- Why this test: git stores the main worktree's `.git` as a directory,

- and a linked worktree's `.git` as a small text file pointing at

- `<main>/.git/worktrees/<name>`. So `[ -d <toplevel>/.git ]` is true

- exactly in the main worktree. This is the same check

- `.claude/hooks/forbid-main-worktree.sh` uses internally; do not

- substitute `git rev-parse --git-dir` (its output is path-shape and

- varies with cwd) or path-matching against `pwd` (every developer's

- clone lives somewhere different).

-

- The `forbid-main-worktree` hook (`.claude/hooks/forbid-main-worktree.sh`)

- will block edits and mutating git commands targeted at the main tree if

- you forget — but the hook is a safety net, not your plan.

- ### Other AI safety hooks (`.claude/hooks/`)

- `guard-bash-safety.sh` (PreToolUse on Bash) blocks:

- - Force-push to `main` / `master` (incl. `+main` refspec) — get explicit user OK first

- - `--no-verify` / `--no-gpg-sign` on commit/push/rebase/merge/am/cherry-pick/pull

- - Staging known-sensitive files (`.env*`, `*.pem`, `*.p12`, `id_rsa`, `id_ed25519`,

- `credentials*`, `secrets*`, `vault_*.key`); also broad `git add -A` / `git add .`

- (CLAUDE.md global rule: stage specific paths)

- - Commit messages containing Claude attribution (`Co-Authored-By: Claude`,

- `🤖 Generated with [Claude Code]`, etc.)

- - `rm -rf` against dangerous targets (`/`, `~`, `$HOME`, `target`, `.git`,

- `/Users`, `/usr`, `/etc`, `/var`, `/opt`, …)

- - Daemon launches: `librefang start`, `target/{debug,release}/librefang start|daemon`

- (port 4545 contention with the user's session — Live Integration Testing is human-only)

- `session-start-worktree-check.sh` (SessionStart) emits a banner telling

- the model whether the session started in the main tree or a linked worktree,

- and warns if `core.hooksPath` hasn't been pointed at `.githooks/`.

- ### Version-controlled git-side hooks (`scripts/hooks/`)

- These run inside `git` itself (regardless of which tool invoked the commit),

- giving defense in depth on top of the Claude Code PreToolUse layer.

- - `pre-commit` — runs `cargo fmt --check` on staged Rust files; CHANGELOG duplicate-`[Unreleased]` guard; `(@user)` attribution check on staged additions to `[Unreleased]` **and on staged `changelog.d/` fragments**, which also rejects a fragment in an unrecognised section directory (#3400); `gitleaks protect --staged` scan against `.gitleaks.toml` (soft-warn if not installed).

- Target: < 2s.

- - `pre-push` — refuses direct pushes to `main` / `master` and exits in

- &lt; 100ms. Heavy verification (clippy, openapi/SDK drift) intentionally

- lives in CI rather than gating every push — see #4532 for the

- rationale. Skip the branch guard for a maintainer hotfix with

- `LIBREFANG_PREPUSH_SKIP=1`.

- - `commit-msg` — rejects commit messages containing Claude / Anthropic attribution (catches heredocs and `git commit -F file` that the PreToolUse Bash hook cannot see), and separately rejects a commit whose *author identity* (`git var GIT_AUTHOR_IDENT`, so the `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL` env overrides are covered) resolves to Claude / Anthropic even when the message itself is clean.

- **Enable once per clone** by running setup:

- ```bash

- just setup # or: cargo xtask setup

- ```

- This sets `git config core.hooksPath scripts/hooks`, which makes the in-repo

- hooks active and keeps them current with `git pull` automatically. The

- `session-start-worktree-check.sh` banner reminds you if it isn't configured

- yet.

- ## Project Overview

- LibreFang is an open-source Agent Operating System written in Rust (24 crates in `crates/`, plus `xtask/`).

- - CLI binary: `target/release/librefang` on Linux/macOS,

- `target/release/librefang.exe` on Windows (debug builds at the

- matching `target/debug/` path)

- - **Core types & utilities**: `librefang-types`, `librefang-http`, `librefang-wire`, `librefang-telemetry`, `librefang-testing`, `librefang-import`

- - **Memory**: `librefang-memory` (SQLite substrate)

- - **Surface**: `librefang-api` (HTTP server + dashboard SPA bundled at `crates/librefang-api/dashboard/`), `librefang-cli`, `librefang-desktop`

- - **Extensibility**: `librefang-skills`, `librefang-hands`, `librefang-extensions`, `librefang-channels`

- **`cargo test` is allowed only when scoped with `-p <crate>` / `--package <crate>`** —

- the unscoped, workspace-wide form is blocked because it contends with the user's

- other sessions on the shared `target/` directory. Full workspace build / test

- runs in CI.

- After every change, run:

- ```

- ### CI test lanes (refs #3696)

-

- CI splits tests into two separate jobs so a unit failure surfaces quickly:

-

- - **Unit-fast** (`Test / Unit (lib+bin)`, ~2 min): `cargo nextest run --workspace -E 'kind(lib) | kind(bin)' --no-fail-fast`

- — lib and binary unit tests only; no integration test binaries. Run this locally for quick iteration.

- - **Integration** (`Test / Ubuntu (shard N/4)`, ~10-20 min): sharded across 4 Ubuntu runners via `--partition hash:N/4`; plus a single macOS job and a 2-way-sharded Windows job, both main-push only.

- Runs all `--tests` targets.

-

- The unit-fast lane uses nextest's `-E 'kind(lib) | kind(bin)'` filter rather than `--lib --bins` because the latter errors with "no library targets found" when a `-p <crate>` selector targets a binary-only crate (`librefang-cli`).

- The expression form matches whichever kinds the selected crates actually have, so the selective CI lane stays green when a PR touches only `librefang-cli/main.rs` (or when a stale-base diff drags it in).

- `librefang-desktop` is not binary-only — it has a lib target carrying 11 tests, so `-p librefang-desktop` resolves fine.

-

- The Windows lane passes `--exclude librefang-desktop` (#6729): the crate's test binary links on Windows but aborts at load with 0xc0000139 (STATUS_ENTRYPOINT_NOT_FOUND), which kills nextest's list phase and takes the whole lane — and therefore CI Gate — down.

- A dedicated `cargo test -p librefang-desktop --all-targets --no-run` step keeps the Windows compile+link coverage; the tests themselves are platform-independent and still run on Ubuntu, macOS and the unit-fast lane.

- Drop both once the missing DLL export is identified.

-

- Local equivalents:

- ```bash

- # Fast lane — unit tests only:

-

- # Full validation — integration tests (mirrors the Ubuntu shard lane):

- cargo nextest run --workspace --no-fail-fast

- ### Verifying without a native toolchain (Docker)

-

- When the host has no native `cargo` (e.g. a macOS box where Rust was never

- installed), do **not** declare a change unverified — run the build inside the

- repo's sanctioned dev image (`Dockerfile.rust-dev`, kept in sync with CI's

- Linux package set). It compiles into a **named volume**, never the host's

- shared `target/`, so it does not contend with the user's sessions and the

- "don't run cargo locally" rule still holds.

-

- ```bash

- # 1. Build the dev image once (cached afterwards):

- docker build -t librefang-rust-dev:latest -f Dockerfile.rust-dev .

-

- # 2. Run any scoped cargo command through it. CARGO_HOME / CARGO_TARGET_DIR

- # point at named volumes (isolated from the host); reuse them across runs

- # so deps compile once. Set PATH explicitly — a login shell ('bash -l')

- # drops the image's /usr/local/cargo/bin from PATH.

- # Prefix link-producing commands (build / test, NOT check) with `mold -run`.

- # The image ships the mold linker; `mold -run` intercepts the child `ld`

- # WITHOUT touching RUSTFLAGS, so it leaves the cached target dir valid while

- # cutting the link phase that every incremental build still pays.

- # Measured on a warm cache, a one-line edit + relink of the kernel-router

- # test binary went 7.1s → 1.7s (4.1x). `cargo check` has no link step, so

- # there is nothing to prefix there.

- # 3. Use a PER-WORKTREE target volume. Sharing one target dir across

- # worktrees that sit on different branches corrupts cargo's incremental

- # cache: cargo reuses compiled metadata from another code state and emits

- # phantom errors — e.g. `missing field 'x'` for a field the current source

- # does not even define. Derive the volume name from the worktree so each

- # branch is isolated. The cargo *download* cache (librefang-cargo) is safe

- # to share — it holds fetched `.crate` files, not compiled artifacts.

- WORKTREE="$(git rev-parse --show-toplevel)"

- TARGET_VOL="librefang-target-$(basename "$WORKTREE")"

- docker run --rm \

- -v "$WORKTREE":/work \

- -v librefang-cargo:/cargo -v "$TARGET_VOL":/target \

- -e CARGO_HOME=/cargo -e CARGO_TARGET_DIR=/target -w /work \

- librefang-rust-dev:latest \

- sh -c 'export PATH=/usr/local/cargo/bin:$PATH; mold -run cargo test -p librefang-api --lib'

- # Reclaim a finished worktree's cache: docker volume rm "$TARGET_VOL"

- # On a small Docker VM, back each volume with a host dir on a big disk first:

- # docker volume create --opt type=none --opt o=bind \

- # --opt device=/big/disk/target-<wt> librefang-target-<wt>

- ```

-

- Scope is still mandatory: `-p <crate>` (or the `kind(lib)|kind(bin)` nextest

- filter), never the unscoped workspace form. The container runs **Linux only**

- — it cannot reproduce a Windows/macOS-specific failure, so for a

- platform-divergent bug write a platform-independent regression test (resolve a

- nonexistent path rather than relying on a host path like `/etc` existing — see

- #5716) or hand the exact command to the human for the missing OS.

- **Primary verification is automated.** The repo has comprehensive

- `#[tokio::test]` integration coverage in `crates/librefang-api/tests/`,

- landed via the #3571 PR series (~30 PRs). Every major route domain is

- exercised against a real axum router via `TestServer` (see

- `start_test_server*` in `tests/api_integration_test.rs`); the canonical

- list is `ls crates/librefang-api/tests/`. CI runs these on every push.

-

- ### What you MUST do for any route / wiring change

-

- 1. **Add a `#[tokio::test]` against `TestServer`** in the matching

- `tests/*.rs` file. Pattern: spawn router via `start_test_server()`,

- hit the endpoint with `reqwest`, assert status and response shape;

- for write endpoints, follow up with a read and assert the side

- effect. This is the canonical replacement for the old curl checklist

- — it catches missing `server.rs` registrations, un-deserialized

- config fields, kernel↔API type drift, and empty/null payloads.

- 2. **Run scoped tests locally**: `cargo test -p librefang-api`

- (workspace-wide `cargo test` is forbidden — see Build & Verify above).

- 3. **Reviewers gate PRs** on the presence of an integration test for

- each new endpoint. PRs that change route shape without a test

- should be sent back.

- ### When live LLM verification is required (HUMAN-only)

- Live daemon + real LLM is needed **only** when the change touches an

- LLM call path or end-to-end prompt/metering wiring that integration

- tests can't simulate (e.g., real provider streaming, real Groq token

- accounting, dashboard HTML smoke). Claude must NOT execute these steps

- — they require `cargo build --release` and a long-lived daemon on

- port 4545, both blocked by `.claude/hooks/`. Prepare commands and

- payloads for the user; they paste output back.

- ```bash

- # Stop any running daemon:

- # Linux/macOS: pkill -f librefang ; sleep 3

- # Windows / Git Bash: tasklist | grep -i librefang && taskkill //PID <pid> //F && sleep 3

- # Build + start with provider key (binary suffix is .exe only on Windows):

- cargo build --release -p librefang-cli

- GROQ_API_KEY=<key> target/release/librefang start &

- sleep 6 && curl -s http://127.0.0.1:4545/api/health

- # Real LLM round-trip + side-effect check:

- AGENT_ID=$(curl -s http://127.0.0.1:4545/api/agents | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['id'])")

- curl -s -X POST "http://127.0.0.1:4545/api/agents/$AGENT_ID/message" \

- -H "Content-Type: application/json" -d '{"message":"Say hello in 5 words."}'

- curl -s http://127.0.0.1:4545/api/budget # cost should have increased

- curl -s http://127.0.0.1:4545/api/budget/agents # per-agent spend visible

- # Cleanup: same OS-specific kill command as above.

- ```

- The daemon command is `start` (not `daemon`).

- ### What was retired

- - The old 8-step manual curl checklist (Steps 1–8) is gone; Steps 4

- and 6 are now `#[tokio::test]` cases. Step 7 (dashboard

- `grep -c newComponentName`) is dropped — it broke under Vite

- minification. Dashboard UI verification is the dashboard test

- suite's responsibility (see `crates/librefang-api/dashboard/`).

- - The "Key API Endpoints for Testing" table is gone; the canonical

- enumeration is the OpenAPI spec (`openapi.json`, regenerated by the

- pre-commit hook) and the integration tests themselves.

- ## Architecture Notes

- - **Deterministic prompt ordering (#3298)**: anything that reaches an LLM prompt — tool definitions, MCP server summaries, skill registries, hand registries, capability lists, env passthrough lists — MUST be ordered before stringifying. Prefer `BTreeMap` / `BTreeSet` over `HashMap` / `HashSet` for those types so the compiler enforces it; otherwise sort at the boundary. HashMap iteration order varies across processes and silently invalidates provider prompt caches even when content is unchanged. Regression tests live next to each boundary — see `kernel::tests::mcp_summary_is_byte_identical_across_input_orders`, `kernel::tests::mcp_summary_inner_tool_list_is_sorted`, and `librefang_skills::registry::tests::all_tool_definitions_is_deterministic_across_insertion_orders` / `tool_definitions_for_skills_is_deterministic_across_insertion_orders`.

- - **Agent workspace layout**: identity files (SOUL.md, IDENTITY.md, etc.) live in `{workspace}/.identity/`, not the workspace root. `read_identity_file()` checks `.identity/` first, falls back to root for pre-migration workspaces. `migrate_identity_files()` is called on every spawn to auto-move any root-level files.

- - **Named workspaces** (`[workspaces]` in agent.toml): declare shared directories with `path` (relative to `workspaces_dir`) and `mode` (`rw` / `r`). Multiple agents sharing the same path never collide — identity files stay in their private `.identity/`. Resolved absolute paths are injected into TOOLS.md as `@name → /abs/path (mode)`. See `workspace_setup.rs: ensure_named_workspaces()`.

- - `KernelHandle` trait avoids circular deps between runtime and kernel

- - `AppState` in `server.rs` bridges kernel to API routes

- - New routes: there is no single `routes.rs` — route handlers live in `crates/librefang-api/src/routes/`, split into per-domain modules (e.g. `agents.rs`, `memory.rs`, `system.rs`), each exporting its own `router()`. `server.rs::api_v1_routes()` composes them with `.merge()`; some domains nest a second level (`routes/system.rs::router()` itself merges `agent_templates`, `approvals`, `pairing`, etc.). To add an endpoint, implement the handler in the matching domain module and merge its `router()` (or add the merge if the module is new). Reflection tests guard against drift: `crates/librefang-api/tests/dead_route_audit_test.rs` and `crates/librefang-api/tests/openapi_path_coverage_test.rs`.

- - Dashboard is React+TanStack Query SPA (not Alpine.js) in `crates/librefang-api/dashboard/`

- - **Dashboard data layer rule**: all API access in pages/components MUST go through hooks in `src/lib/queries/` and `src/lib/mutations/`. No `fetch()` or `api.*` calls inline in pages/components. Adding a new endpoint = add a query/mutation hook in the matching domain file, then import it. See `crates/librefang-api/dashboard/AGENTS.md` for details

- - **Dashboard query keys**: always use the factories in `src/lib/queries/keys.ts`. Never inline `["foo","bar"]` arrays. Every factory must be hierarchical (`all` / `lists()` / `list(filters)` / `details()` / `detail(id)`) so `invalidateQueries({ queryKey: xxxKeys.all })` invalidates the whole domain

- - **Dashboard mutations**: each mutation with side-effects must call `invalidateQueries` with factory keys in `onSuccess` (or `onSettled`). Colocate invalidation with the mutation hook, not at call sites

- - Config fields need: struct field + `#[serde(default)]` + Default impl entry + Serialize/Deserialize derives

- - **Trait injection pattern**: When runtime needs functionality from extensions/kernel, define a trait in runtime and implement it in kernel (e.g., `McpOAuthProvider`). Never make runtime depend on extensions (circular dep).

- - **Auth middleware allowlist**: Unauthenticated endpoints must be added to the `is_public` allowlist in `middleware.rs` — NOT by reordering routes in `server.rs`. The auth layer applies to all routes.

- - **Docker callback URLs**: Never bind ephemeral localhost ports for OAuth callbacks in daemon code — the port is unreachable from outside Docker. Route callbacks through the API server's existing port instead.

- - **MCP OAuth flow**: Entirely UI-driven — daemon only detects 401 and sets `NeedsAuth` state. PKCE + callback handled by API layer (`routes/mcp_auth.rs`). Dynamic Client Registration (RFC 7591) used when server has `registration_endpoint` but no `client_id`.

- - `session_mode` in `AgentManifest` (agent.toml, **not** config.toml) controls whether automated invocations reuse the persistent session (`"persistent"`, default) or create a fresh one (`"new"`). Per-trigger override via `Trigger.session_mode: Option<SessionMode>`. Per-cron override via `CronJob.session_mode: Option<SessionMode>`. Resolution order: per-trigger / per-job override > agent manifest default. Session resolution lives in `execute_llm_agent` (grep `kernel/mod.rs` for the function).

- - **Honors `session_mode`**: event triggers, `agent_send`, **cron jobs** (since #3597 / #3657 — see below).

- - **Ignores `session_mode`**: channel messages (always `SessionId::for_channel(agent,"<channel>:<chat>")`), forks (forced `Persistent` to preserve prompt cache).

- - **Cron + `session_mode`** (resolution helper: `cron::cron_fire_session_override`):

- - Effective mode = per-job `CronJob.session_mode` > agent manifest `session_mode` > historical `Persistent`.

- - `Persistent` (or unset): the cron tick synthesizes `SenderContext{channel:"cron"}` and `send_message_full` derives `SessionId::for_channel(agent,"cron")`, so all fires of all cron jobs for that agent share one `(agent,"cron")` persistent session (historical behaviour, prompt-cache reuse).

- - `New`: `cron_fire_session_override` returns an explicit `SessionId::for_cron_run(agent, "<job_id>:<rfc3339_fire_time>")` which is passed as `session_id_override` into `send_message_full`. The override path wins over the channel-derived branch, so each fire lands on its own deterministic, isolated session — prior fires never leak into the current run, and the persistent `(agent,"cron")` session stays untouched.

- - When creating a trigger or cron, consciously pick: `Persistent` (continuity, cache reuse) vs `New` (isolation, fresh context per fire).

- - **Message-history trim cap** is configurable per-agent

- (`agent.toml: max_history_messages`) and globally

- (`config.toml: max_history_messages`). Default is

- `DEFAULT_MAX_HISTORY_MESSAGES = 60`; values below

- `MIN_HISTORY_MESSAGES = 4` are clamped up with a warning.

- Resolution: agent override > kernel config > compiled default. See

- `docs/architecture/message-history-trimming.md`.

- - **Per-agent `proactive_memory` / `skill_workshop` / `compaction`

- overrides live in `agent.toml`, NOT `config.toml`** (#5476).

- `KernelConfig` has no `agents` field, so a block like:

- ```toml

- # ~/.librefang/config.toml — silently ignored, NOT honoured

- [agents.my-agent.proactive_memory]

- auto_memorize = true

- ```

- parses but never feeds into any `AgentManifest`. The kernel emits a

- targeted `WARN` at boot and on `POST /api/config/reload` pointing

- operators at the correct surface (see

- `KernelConfig::detect_misplaced_per_agent_overrides`); the

- load-bearing path is the agent's own manifest:

- ```toml

- # ~/.librefang/workspaces/agents/my-agent/agent.toml — per-agent override

- [proactive_memory]

- auto_memorize = true

- ```

- Same shape for `[skill_workshop]` and `[compaction]`. Inside a

- `HAND.toml` the override sits under `[agents.<name>.<key>]`, which

- *is* read because `HandManifest` does have an `agents` table —

- `config.toml` does not.

- - **Trigger dispatch concurrency** has three layered caps, scoped to

- the **trigger dispatcher only** (`agent_send`, channel bridges, and

- cron still serialize at the existing per-agent / per-session locks

- inside `send_message_full`). Global `Lane::Trigger` semaphore

- (`config.toml: queue.concurrency.trigger_lane`, default 8) caps

- total in-flight trigger fires kernel-wide. Per-agent semaphore

- (`agent.toml: max_concurrent_invocations`, fallback

- `queue.concurrency.default_per_agent` default 1) caps that one

- agent's parallelism. Per-session mutex applies inside

- `send_message_full` only when the dispatcher materialized a fresh

- `SessionId` — which it does for `session_mode = "new"` fires. The

- resolver auto-clamps `persistent + cap > 1` to 1 with a `WARN` log

- (concurrent writes to a single session's history are undefined).

- Per-agent caps are NOT invalidated on manifest hot-reload — to pick

- up a new cap, **kill the agent and let it respawn** (or restart the

- daemon); an in-place activate/status flip will silently keep the old

- cap. See `docs/architecture/trigger-dispatch-concurrency.md`.

- - **Config hot-reload classification**: which `KernelConfig` fields

- hot-reload, which require a restart, and which are read-live/noop is

- decided by `build_reload_plan` in

- `crates/librefang-kernel/src/config_reload.rs`. The canonical

- ops-facing reference table (one row per field, derived from that

- function and drift-guarded by a test) lives at

- `docs/operations/config-reload.md` — consult it before assuming a

- config edit takes effect on `POST /api/config/reload`.

- - **Skill workshop** (#3328) passively captures teaching signals from

- successful turns into draft skills under

- `~/.librefang/skills/pending/<agent>/<uuid>.toml`. **Default-OFF —

- opt-in per agent** by setting `[skill_workshop] enabled = true` in

- the agent's manifest (`agent.toml`, or the matching `[agents.<name>]`

- section of a `HAND.toml`). Once enabled, the conservative knob set

- applies by default: `auto_capture = true`,

- `review_mode = "heuristic"` (no LLM call),

- `approval_policy = "pending"` (every candidate waits for human

- approve / reject), `max_pending = 20`. Source of truth is

- `SkillWorkshopConfig::default()` in

- `crates/librefang-types/src/agent.rs` — `enabled: false` per the

- original #3328 acceptance criteria.

- Three signals — `ExplicitInstruction` ("from now on always …"),

- `UserCorrection` ("no, do it like …"), `RepeatedToolPattern` (same

- tool sequence ≥ 3 turns). Approval routes through

- `evolution::create_skill`, so the prompt-injection scan runs at both

- `save_candidate` and `approve_candidate` — every artefact visible to

- the agent has crossed the same security boundary as a marketplace

- skill. LLM refinement (`review_mode="threshold_llm"`) uses the

- dedicated `AuxTask::SkillWorkshopReview` slot and the cheap-tier

- provider chain; when no cheap-tier credentials are configured the

- workshop returns `Indeterminate` rather than billing the operator's

- primary provider, blocking a financial-DoS regression. UUID

- validation guards every storage entry that addresses files by id, so

- a non-UUID id never reaches `Path::join`. CLI: `librefang skill

- pending list / show / approve / reject`. HTTP:

- `GET/POST /api/skills/pending[…]`. Dashboard:

- `PendingSkillsSection` on the Skills page. See

- `docs/architecture/skill-workshop.md`.

- ## Git Conventions

- - **Format**: Use conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `ci:`, `perf:`, `test:`)

- - **Changelog entry = a new file under `changelog.d/`, NOT an edit to `CHANGELOG.md`.**

- Appending to the single `## [Unreleased]` section conflicts with every other open PR that does the same, in a file where the conflict carries no information — both sides are correct and the resolution is always "keep both".

- Write one fragment per entry in the section directory matching its `### ` heading (`added/`, `fixed/`, `changed/`, `security/`, `documentation/`), named after the PR or issue number so fragments sort usefully: `changelog.d/fixed/6623-wire-max-content-chars.md`.

- The file holds the bullet body **without** the leading `- `, one sentence per line, continuation lines indented two spaces, ending `(#PR) (@your-github-login)`.

- Format and a worked example: `changelog.d/README.md`.

- `cargo xtask collect-fragments` folds fragments into `## [Unreleased]` and deletes the files consumed; `cargo xtask release` runs it before cutting the dated section, so a fragment reaches the CHANGELOG exactly as a hand-written bullet does.

- Editing `## [Unreleased]` directly still works and assembly appends to whatever is already there — but the direct edit is the thing that conflicts, so don't reach for it.

- A fragment in an unrecognised section directory is rejected by `scripts/check-changelog-attribution.py`, because assembly has no heading to render it under and would drop it silently.

- **The entry ends up in the GitHub release body verbatim.**

- `cargo xtask release` moves the whole `## [Unreleased]` body into the dated `## [VERSION]` section it cuts, leaving the heading behind and empty for the next cycle, and `.github/workflows/release.yml` slices that section into the release notes, the Dev.to article, and the social post.

- Generated `- <PR title> (#N) (@author)` lines fill only the gaps: a PR whose number appears in a curated bullet's trailing `(#N)` group gets no generated line, so it is described once, in the words someone chose.

- Write the entry as prose that explains *why*, not a restatement of the PR title — the title is already covered for free.

- - **No AI / Claude attribution** in commit messages, PR bodies, or

- comments — see "Commit & PR hygiene" under GitHub Collaboration below

- for the canonical rule (the `commit-msg` hook enforces it server-side

- too).

- - **Worktree**: Use `git worktree add` on an external disk for new features; fall back to `/tmp/librefang-<feature>` only if no external disk is available. Never develop on the main worktree

- - **Worktree continuation = drive to PR**: When asked to continue half-done work in an existing worktree (uncommitted changes or unmerged commits), the workflow is **commit → push → open or update PR**. Don't stop at "local commits only". A new branch needs a fresh PR; an existing branch with an open PR gets a follow-up push to update it. Anything left in the worktree counts as real work — including a regenerated `Cargo.lock` after rebase. Commit it together with the rest of the change; do not `git checkout` it away.

- - **Re-created worktree → `git fetch` and compare against `origin/<branch>` BEFORE editing.** When you `git worktree add` for a branch that already exists on the remote (e.g. after removing and re-creating its worktree, or resuming an active PR), the remote tip may be **ahead** of your base — collaborator pushes, the `auto-update-branches` cron, or the `openapi-drift` auto-codegen commit all move it without your involvement. Editing on a stale base and force-pushing **silently clobbers that newer work**. A non-fast-forward push rejection is the *last* line of defense, not the plan: fetch first, diff `HEAD..origin/<branch>`, and rebase/rebuild your change on the real tip. Isolation hides drift — compensate by checking the remote, every time you re-enter a worktree you did not just create.

- LibreFang has no column-width rule for prose.

-

- The only legitimate line break inside a paragraph is at a complete sentence boundary (after `.`, `?`, `!`, or other terminal punctuation).

- One sentence = one line, regardless of length.

- Editors soft-wrap, viewers reflow, and the diff stays clean when a single word changes inside a sentence.

-

- This rule applies universally:

-

- - Markdown documentation anywhere in the repo (`docs/**`, crate / project READMEs, `AGENTS.md`, `CLAUDE.md`, this file, all the rest).

- - `CHANGELOG.md` bullets — one sentence per line within a bullet.

- - PR titles, PR bodies, and issue / PR comments posted via `gh pr create`, `gh pr edit`, `gh issue comment`, etc.

- - Source code doc-comments (`//!`, `///`, `#`-style docstrings, JSDoc, …) and any multi-line free-form prose comment block.

- The doc renderer joins consecutive prose lines anyway; splitting mid-sentence just fragments `git blame` and obscures intent.

- - Commit message bodies.

- Subject lines still follow git's own ~72-char display-truncation convention — that is a tooling limit, not prose wrapping.

- Hand-tuned column wraps split noun phrases and subject-verb pairs at awkward points, force a single-word edit to re-flow the whole paragraph (which pollutes `git blame` and review diffs), and carry no semantic information.

- Break where the writer *meant* to break — at sentence ends — and let viewers reflow.

- Pre-existing files in the repo that were written under the old column-wrap convention are not retroactively rewrapped; the rule applies to *new* prose and to any paragraph an agent is already touching.

- Do not rewrap an untouched paragraph just to enforce the rule.

- LibreFang is an open-source project with heavy AI-assistant traffic. The

- rules below codify the boundaries summarised in `AGENTS.md` ("AI Agent

- Collaboration") so that maintainers stay in control of their own PRs and

- issue threads.

-

- ### Touching other people's work

-

- - **Don't close PRs or issues opened by others** unless the user (the

- maintainer) directly instructs you to. By default, post a comment

- recommending closure with the linking commit / PR and let the

- maintainer pull the trigger. When directed to close, the close

- comment must state the substantive reason (review bugs, superseded

- by, scope mismatch) so the original author understands what went

- wrong — do not attribute the close to "AI" / "Claude", the reason

- itself is what matters.

- - **Force-push only to your own branches, only before review.** Once a

- reviewer has loaded the diff, prefer fixup commits or a follow-up PR

- over rewriting history. Force-push to `main` / `master` is blocked by

- `guard-bash-safety.sh` and requires explicit user OK regardless.

- - **Don't reassign, re-label, or re-milestone** issues / PRs you did not

- open unless directed. Self-assigning a triage label or adding

- `needs-review` is auto-OK; flipping `priority` / `release` labels is

- not.

-

- ### Commit & PR hygiene

-

- - **No Claude / Anthropic / AI attribution** in commit messages, PR

- bodies, or issue comments. The `commit-msg` git hook rejects matching

- strings; the PreToolUse Bash hook catches the inline-flag form. Don't

- try to route around either — the rule exists because attribution

- pollutes `git log` and signals provenance the project does not want to

- imply.

- - **One PR ↔ one issue (or one tight cluster).** Don't bundle unrelated

- refactors with the requested change. If you find a real problem

- out-of-scope, open a separate issue or follow-up PR; mention it in the

- current PR's "Out-of-scope follow-ups" section.

- - **Fix what you found — don't punt it to a "follow-up".** Anything you

- noticed while reading or writing the code in this PR is in-scope by

- definition: review nits, mismatched HTTP status codes, missing log

- fields, redundant lookups, stale comments, type-shape inconsistencies,

- small clippy noise. Treat the phrases "follow-up", "long-term

- improvement", "next PR", "future cleanup", "out-of-scope follow-up

- issue", "leave for later" as red flags in your own review or summary

- output — they almost always mean "I saw the problem and decided to

- defer the work". The bar to defer: would fixing it require touching a

- *different* crate or domain than the one you're already in? If no, fix

- it in this PR. If yes, surface the question to the human reviewer with

- the concrete trade-off and ask before deferring; don't decide

- unilaterally. The same rule applies when you re-evaluate a deferred

- item and decide it's a "non-issue" — you must back that decision with

- the file/line evidence that contradicts the original concern, in the

- same response. "I looked again and it's fine" without evidence is

- another form of punting.

- - **PR body must enumerate** the substantive changes, the verification

- performed (integration test names, `cargo check --workspace --lib`

- output, scoped `cargo test -p <crate>` runs), and any deferred work.

- Bullet form, no marketing prose.

-

- ### CI wait policy

-

- CI is shared infrastructure and frequently slow. Polling it from an AI

- session burns turns without producing information.

-

- - **Total polling budget: ~5 minutes, in 60–270s chunks.** Anthropic's

- prompt cache TTL is 5 minutes, so keep each wake-up inside that

- window to keep the cache warm; ~300s is the worst case (cache miss

- without amortizing). Don't reach for 1200s+ "save my turns" waits

- here — that violates the 5 min total cap and reintroduces the long

- `gh run watch` / sleep behaviour the policy is meant to prevent.

- After the total budget is spent, push, leave the run URL in the PR

- / report, and **stop**. (Long waits *are* appropriate elsewhere —

- e.g. an autonomous-loop tick polling for an external job — just not

- for in-session CI polling.)

- - **Don't pre-emptively re-run a check** that has not yet failed. Only

- retry after a recorded failure, and only once.

- - **Don't open follow-up issues or pivot the plan** while waiting for CI

- or review. If you cannot make further progress without information you

- do not have, the correct action is to report status and yield — not to

- invent more work.

- - **Don't add reviewers, flip `ready-for-review`, or `gh pr ready`** on

- someone else's behalf, and don't re-request review on your own PR

- unless a maintainer has explicitly asked you to ping them. Maintainers

- pull work into their queue; AI agents do not push it onto theirs.

-

- ### Batch merging: the Actions runner pool is the bottleneck, not the merge

-

- The `librefang` org is on the **free** GitHub plan and every job targets the hosted `ubuntu-latest` pool, so concurrent runners are capped org-wide.

- Every push to `main` re-triggers the full workflow set, and so does every push to a PR branch.

- Merging a backlog back-to-back therefore spends the whole concurrency budget on runs nobody will ever read: after 86 consecutive merges the queue held 657 jobs with **zero** executing, the oldest waiting 67 minutes, and the only run whose result mattered — CI Gate on the current `main` HEAD — was stuck behind 85 superseded ones.

-

- When clearing more than ~10 PRs:

-

- - **Merge in batches and let the queue drain between them.**

- Check `gh api 'repos/librefang/librefang/actions/runs?status=in_progress&per_page=1' --jq .total_count` — if it reads 0 while jobs are queued, the pool is saturated and nothing will progress until something is cancelled or times out.

- - **Cancel superseded runs rather than waiting them out.**

- A queued run is dead weight when its `head_sha` is no longer its branch's tip: on a PR branch a newer commit has replaced it, and on `main` only HEAD's checks are ever consulted.

- Resolve tips with `git ls-remote origin` and compare, rather than assuming the newest run per branch is the live one.

-

- ```bash

- # Queued runs whose head_sha is no longer the branch tip, cancelled.

- gh api --paginate 'repos/librefang/librefang/actions/runs?status=queued&per_page=100' \

- --jq '.workflow_runs[] | "\(.id)\t\(.head_branch)\t\(.head_sha)"' > /tmp/q.tsv

- git ls-remote origin | awk '$2 ~ /^refs\/heads\//{sub("refs/heads/","",$2); print $2"\t"$1}' > /tmp/tips.tsv

- awk -F'\t' 'NR==FNR{tip[$1]=$2; next} ($2 in tip) && tip[$2]!=$3 {print $1}' /tmp/tips.tsv /tmp/q.tsv \

- | while read id; do gh api -X POST "repos/librefang/librefang/actions/runs/$id/cancel" >/dev/null; done

- ```

-

- Leave runs whose branch no longer exists alone — a deleted branch means the PR already merged or closed, and its checks are nobody's gate.

-

- **Never cancel a run whose `head_sha` *is* its branch's tip, even to free capacity.**

- `CI Gate` fails on `cancelled` exactly as it does on `failure`, and it does not re-evaluate when the lane is later re-run: the gate stays red while every lane above it reads green.

- Cancelling live runs to unblock one urgent PR left 25 healthy PRs looking broken, each showing `CI Gate: one or more lanes failed or were cancelled` as its only red check, and each needing a fresh push to clear.

- The superseded-run rule above is safe precisely because it never touches a tip.

- - **A stalled queue is not a CI failure.** Before diagnosing a PR as broken, confirm jobs are actually executing. `runner_name` empty across the board (`gh api repos/librefang/librefang/actions/runs/<id>/jobs --jq '.jobs[].runner_name'`) means unassigned, i.e. starved for capacity, not failing.

- - **`CI Gate` red with every lane green means the gate saw a cancellation, not a defect.**

- Read the gate's own log before touching the branch: `CI Gate: one or more lanes failed or were cancelled` with no failing lane is a stale verdict, cleared by re-running CI (update-branch or an empty push), not by changing code.

-

- ### Two green PRs can still break `main` together

-

- The `main` ruleset does not set `strict_required_status_checks_policy`, so a PR merges on the CI it ran against **its own base**, which may be many commits behind.

- Two PRs that touch the same file on the same stale base are each validated in isolation and neither result says anything about the combination.

-

- This is not hypothetical, and text-level conflict detection does not catch it — git sees edits to different lines and merges cleanly:

-

- > #6814 added two `redact_metadata(&Value::String(…))` call sites while the function still took a reference.

- > #6815 changed the signature to take the value by owner and updated the call sites *it* could see.

- > Both branched from `37937950b`, both were fully green, and they were merged two seconds apart.

- > The result did not compile, and because the break sits in `#[cfg(test)]` code it only surfaced on the one lane that builds test targets — turning `Build / Linux aarch64` red on `main` and failing the CI Gate of 30+ open PRs that had nothing to do with it.

-

- So when merging several PRs in one sweep:

-

- - **Group by file, not just by conflict status.** Before starting, map changed files to PRs (`gh pr view <n> --json files`) and treat any file touched by more than one PR as a serialization point: merge one, let the others pick up the new `main`, and re-check.

- - **Second and later PRs in a group need a fresh check run, not just a clean merge.** `MERGEABLE` only means git can splice the text. Push the branch onto current `main` (or use the update-branch API) so CI re-runs against the combination that will actually land.

- - **Watch for a signature or contract change anywhere in the group.** A PR that changes a function's parameters, return type, or ownership is the dangerous side of the pair — any *other* PR in the batch that calls it was written against the old contract.

- - **After a batch, verify `main` itself rather than assuming.** Green on each PR does not imply green on the merge result; check the CI Gate on the new `main` HEAD before starting the next batch.

-

- ### Issue / PR comment etiquette

-

- - **At most two follow-up comments** on the same thread without human

- input. After that, stop and wait — repeated AI-generated pings on a

- silent thread are noise, not progress.

- - **Don't comment on threads you have no action on.** "Looks good"

- drive-bys from an AI account add nothing.

- - **When you reply, link evidence:** commit SHAs, file paths, test

- names. No vibes-only comments.

-

- ### Conflict resolution

- - **Latest maintainer intent wins.** When rebasing or resolving merge

- conflicts that touch a human-authored hunk, keep the maintainer's

- edit. If the two sides genuinely disagree, surface the conflict in the

- PR body and ask — don't silently pick the smaller diff.

- - **Preserve both sides' intent** during conflict resolution. Dropping a

- hunk because "it'll be reapplied later" is how regressions land.

- - Windows: `librefang.exe` may be locked if the daemon is running —

- use `cargo check --lib` or kill the daemon first. (Linux / macOS

- let you overwrite a running binary, so this is not an issue there.)

- - `PeerRegistry` is `Option<PeerRegistry>` on kernel but `Option<Arc<PeerRegistry>>` on `AppState` — wrap with `.as_ref().map(|r| Arc::new(r.clone()))`

- - Config fields added to `KernelConfig` struct MUST also be added to the `Default` impl or build fails

- - `AgentLoopResult` field is `.response` not `.response_text`

- - CLI command to start daemon is `start` not `daemon`

- - When adding `Option<Arc<dyn Trait>>` fields to structs that derive `Serialize`/`Deserialize`/`Clone`/`Debug`, mark them `#[serde(skip)]` and implement the affected traits manually

- - `ErrorTranslator` (from `RequestLanguage`) is `!Send` — any `.await` must happen AFTER `drop(t)`, or the axum handler will fail with a cryptic `Handler<_, _>` trait bound error

- - `LIBREFANG_VAULT_KEY` env var must base64-decode to exactly 32 bytes (use `openssl rand -base64 32` which gives 44 chars). 32 ASCII chars ≠ 32 bytes.

- - Linux desktop: `zbus/tokio` conflicts with Tauri's worker threads — calling blocking session bus connections (like tauri-plugin-notification/notify-rust) inside a Tokio worker thread panics with "Cannot start a runtime from within a runtime."

- Force the `async-io` backend of the zbus/ksni crate to run it on a separate reactor.

- - `CLAUDE_CODE_HOME` env var overrides the home directory used by the `claude-code` driver when it spawns the Anthropic `claude` CLI subprocess. **LibreFang-private contract — the Anthropic CLI itself does not read this variable**; the driver resolves it kernel-side and projects the value onto the platform-native home var (`$HOME` on Unix, `%USERPROFILE%` on Windows) before spawn. Distinct from the existing `LIBREFANG_HOME` (which relocates the daemon's data dir — see `crates/librefang-kernel/src/config.rs:librefang_home`); the two never share a value. Containers that drop privileges to a numeric uid without a matching passwd entry inherit a placeholder home (`/nonexistent` on glibc, `/var/empty` on BSD/Alpine, `/dev/null` on some hardened images) — set `CLAUDE_CODE_HOME` in the orchestrator manifest / kernel-boot wrapper so the spawned CLI can find `~/.claude/.credentials.json`. The override is unused when the inherited platform home already resolves to a real on-disk directory; when it is set but points at a non-directory the driver emits a `WARN` log and falls back to the inherited platform home rather than honouring the broken override.

- - When parallel agents modify the same crate, `Option::None` defaults for new fields will silently compile but disable features. Always write integration tests at the injection site, not just the implementation site.

- - On Windows: use `taskkill //PID <pid> //F` (double slashes in MSYS2/Git Bash)