Merge branch 'distributed-singing-stonebraker': distributed agent context reorganization

Mirror of the lab repo's reorganization for the linuxcnc fork:

- CLAUDE.md auto-loads via the documented @AGENTS.md import. Standalone
  linuxcnc sessions get the fork's AGENTS.md inlined automatically;
  no bootstrap rituals.
- Renamed agents.md → AGENTS.md.
- Trimmed AGENTS.md from 264 → 146 lines. Added Public fork warning
  (don't leak private project context), Upstream composability rule
  (don't modify upstream-authored files, don't create new human docs
  at root that overlap with upstream README/scripts), Safe Action
  Protocol, Session startup checklist, File ownership matrix, Memory
  routing, Git conventions, and a compact Build/Run/Test/Clean section.
  The Upstream PR prep section was trimmed from ~60 lines to ~14
  lines (summary + router to memory/reference_upstream_pr_workflow.md
  for the full procedure).
- Created in-repo MEMORY.md (pure index) and TODO.md (peer file) at
  fork root.
- Migrated 5 fork-relevant entries into linuxcnc/memory/:
  feedback_public_fork.md (with the new 'grep is necessary but not
  sufficient' contextual-leak lesson), reference_fork_setup.md
  (8-step setup procedure extracted from AGENTS.md One-Time Setup),
  reference_teleop_velocity_bug.md (upstream PR LinuxCNC#3933 context),
  reference_upstream_pr_workflow.md (full upstream contribution
  procedure).
- Three Phase 4c entries (reference_runtime_latest.md,
  reference_test_timings.md, reference_halcompile_workflow.md) were
  initially copied here, then removed in follow-up commits when the
  operator caught that they describe private project work that uses
  the fork rather than fork-side knowledge. The straddle rule put
  them in the private repo's memory/ instead. Their delete-overlay
  commits stay in branch history; the file content is no longer in
  the fork tree.
- Disabled harness auto-memory via .claude/settings.json:autoMemoryEnabled=false
  with a gitignore exception so the setting reaches every cloner.
- Deleted the legacy lowercase memory.md (consolidated into AGENTS.md
  rules and Gotchas/Environment sections).
- README.md and other upstream-authored files NOT touched, per the
  Upstream composability rule.

8 commits, all on session branch distributed-singing-stonebraker.
Multiple public-fork hygiene passes applied during the migration —
final tree is leak-free per both literal-path grep and contextual
human review.

Author: igor

.claude/settings.json

@@ -0,0 +1,46 @@
+{
+  "autoMemoryEnabled": false,
+  "permissions": {
+    "allow": [
+      "Bash(make:*)",
+      "Bash(git:*)",
+      "Bash(halcmd:*)",
+      "Bash(halrun:*)",
+      "Bash(halcompile:*)",
+      "Bash(linuxcnc:*)",
+      "Bash(python3:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(wc:*)",
+      "Bash(file:*)",
+      "Bash(which:*)",
+      "Bash(command -v:*)",
+      "Bash(echo:*)",
+      "Bash(env)",
+      "Bash(pgrep:*)",
+      "Bash(dpkg:*)",
+      "Bash(apt-cache:*)",
+      "Bash(apt list:*)",
+      "Bash(mkdir:*)",
+      "Bash(cp:*)",
+      "Bash(chmod:*)",
+      "Bash(sed:*)",
+      "Bash(tar:*)",
+      "Bash(sudo:*)",
+      "Read(//usr/**)",
+      "Read(//tmp/**)",
+      "Read(//proc/**)",
+      "Read(//etc/**)",
+      "Read(//home/igor/**)",
+      "WebFetch(domain:linuxcnc.org)",
+      "WebFetch(domain:forum.linuxcnc.org)"
+    ],
+    "additionalDirectories": [
+      "/tmp"
+    ]
+  }
+}

.gitignore

@@ -57,4 +57,6 @@ position.txt
 *.*-stamp
 # Ignore VSCode settings
 .vscode/settings.json
-.claude/
+.claude/*
+# Exception: project settings like autoMemoryEnabled must reach every cloner
+!/.claude/settings.json

AGENTS.md

@@ -0,0 +1,146 @@
+# LinuxCNC Fork — Agent Guidelines
+
+Reference: https://linuxcnc.org/docs/devel/html/code/building-linuxcnc.html
+
+Build mode: **run-in-place**, **uspace** (Preempt-RT / non-realtime simulator).
+Do not build docs or packages unless explicitly asked.
+
+## Public fork warning
+
+This is `is-primary-dev/linuxcnc`, a **public** fork of upstream LinuxCNC. **Never reference private repo names, paths, hardware specifics, internal customer data, or personal information in any committed file.** Cross-references only go from private repos → public fork, never public → private. Before committing, grep for any leaked terms. See `memory/feedback_public_fork.md`.
+
+## Upstream composability
+
+This is a fork. Every commit must stay composable with upstream LinuxCNC pulls — modifications to upstream files create merge conflict surface on every `git pull upstream master`.
+
+- **Do NOT modify upstream-authored files** — `README.md`, `INSTALL`, `COPYING`, `AUTHORS`, `src/`, `lib/`, `configs/`, `docs/`, `tcl/`, `python/`, `scripts/`, `debian/`, etc. If a fix needs to go upstream, use the **Upstream PR prep** workflow below — never modify upstream files directly in fork master.
+- **Do NOT create new human docs at linuxcnc root** — `DEVELOPMENT.md`, `TESTING.md`, `BUILD.md` would overlap with upstream's `README.md` and `scripts/` and may collide on syncs. Fork-specific dev notes go in `memory/reference_*.md`, lazy-loaded.
+- **Fork-only additions go in fork-only files:** `AGENTS.md`, `CLAUDE.md`, `MEMORY.md`, `memory/`, `TODO.md`, `.claude/settings.json` (gitignore exception), `agent-helpers/`.
+- **If unsure whether a file is upstream-owned, ask the operator before editing.** Default to "don't touch."
+
+## Safe Action Protocol
+
+All agent actions that touch shared state (build, test, git, halcmd, file edits to the deployed source tree) go through `agent-helpers/safe-agent-action.sh`. The wrapper is the single permission entry — no per-command prompts.
+
+**Wrapper covers:**
+- `git <subcommand>` — feature-branch git work (commit, push, fetch, rebase, merge, checkout, reset, clean, cherry-pick, worktree, `commit --amend`, force-push to feature branches)
+- Session lifecycle: `session-start <name>`, `session-push`, `session-merge <name>`
+- Build: `make`, `make-raw`, `setuid`, `configure`, `autogen`, `syntax-check`
+- Read-only inspection: `grep`, `find`, `view`, `tail`, `du`, `ps`, `pgrep`
+- LinuxCNC: `linuxcnc`, `halcmd`, `halrun`, `halcompile`, `runtests`, `latency-watch`
+- Upstream contribution: `upstream-pr-prep` (see Upstream PR prep section below)
+
+**Built-in Read/Edit/Write/Grep/Glob do NOT need the wrapper** — they don't go through Bash.
+
+**Bare git is permitted only for these cases the wrapper intentionally refuses:**
+1. `git push` / `git merge` targeting `master` or `main`
+2. `git push` to the `upstream` remote
+3. `git filter-branch`, `git update-ref`
+4. `git branch -D master` / `branch -M main`
+
+The merge-to-master sequence (`git switch master && git merge --no-ff <feature> && git push`) is the canonical bare-git case. **Merging to master is always an operator approval gate.** "Continue" is NOT merge approval — ask explicitly ("merge now?") and wait for a clear yes.
+
+**Subagents don't inherit wrapper permission.** When spawning one (Agent tool), tell it to use built-in Read/Grep/Glob, or to call `safe-agent-action.sh` explicitly.
+
+**If the wrapper lacks a subcommand you need, add it** (one `case` branch in the script) rather than falling back to bare bash.
+
+## Session startup
+
+Pre-flight checklist before any work in a new session:
+
+1. **Read AGENTS.md** (auto-loaded via `CLAUDE.md` → `@AGENTS.md`).
+2. **Scan `MEMORY.md`** for topic-relevant entries; read individual `memory/*.md` entries on demand.
+3. **Create/switch to a session branch** via `agent-helpers/safe-agent-action.sh session-start <plan-name>`. Plan file basename (without `.md`) is the branch name.
+4. **Use the wrapper from command #1.** No bare git, no bare grep, no subagents shelling out.
+
+If the user hands off a task, acknowledge it, run the checklist, then start work.
+
+## File ownership and audience separation
+
+| File | Audience | Purpose |
+|---|---|---|
+| `README.md` (upstream) | Human + agent | Upstream LinuxCNC build/usage docs |
+| `AGENTS.md` | Agent only | Hard rules + protocols. Always loaded via `CLAUDE.md`. |
+| `MEMORY.md` | Agent only | One-line-per-entry index. Pure index. |
+| `memory/*.md` | Agent only | Topic knowledge, judgments, learnings. Lazy-loaded on demand. |
+| `TODO.md` | Human + agent | Deferred work, known issues, plain bullets. |
+| `agent-helpers/README.md` | Human + agent | Wrapper and helper script docs. |
+
+**Routing rule:** when AGENTS.md covers a topic that has a human doc (upstream `README.md`, `agent-helpers/README.md`), AGENTS.md should **point**, not **restate**.
+
+## Memory routing
+
+`MEMORY.md` is a one-line-per-entry index. **Scan it at session startup** (step 2 of the checklist) and read individual `memory/*.md` entries on demand when task-relevant.
+
+Auto-memory (harness-level) is **disabled** via `.claude/settings.json:autoMemoryEnabled=false`. In-repo `memory/` is the sole source of truth for persistent agent knowledge.
+
+## Git conventions
+
+- **`origin`** = `https://github.com/is-primary-dev/linuxcnc.git` (the fork). All `git push` goes here.
+- **`upstream`** = `https://github.com/LinuxCNC/linuxcnc.git` (main project). Pulled from, never pushed to (the wrapper refuses).
+- **Sync from upstream:** `git fetch upstream && git merge upstream/master`.
+
+## Build / Run / Test / Clean
+
+```bash
+# Build (incremental, auto-restores setuid)
+agent-helpers/safe-agent-action.sh make -j$(nproc)
+
+# Build a single target
+agent-helpers/safe-agent-action.sh make ../bin/<name>
+
+# Run with an INI (auto-sources rip-environment, requires DISPLAY=:0)
+agent-helpers/safe-agent-action.sh linuxcnc <path-to-ini>
+
+# Test
+source scripts/rip-environment && runtests
+# Options: -v verbose, -s stop on failure, -n keep artifacts, -u skip sudo tests
+
+# Clean
+agent-helpers/safe-agent-action.sh make-raw clean
+agent-helpers/safe-agent-action.sh make-raw distclean   # full reset, must re-run setup steps 4–5
+```
+
+**Common sim configs:**
+- `configs/sim/axis/axis.ini` — classic Axis GUI
+- `configs/sim/qtdragon_hd/qtdragon_hd_xyz/qtdragon_hd_xyz.ini` — QtDragon HD
+
+**Background launch with output capture:** `script -qec "DISPLAY=:0 linuxcnc" /dev/null 2>&1` and use Bash `run_in_background`. `script` provides a pseudo-TTY — without it, the launcher redirects output to temp files that are deleted on exit. Spawn a monitoring agent to watch the background output, report status, and summarize when done.
+
+**Full build with documentation** (only when asked, significantly slower):
+```bash
+cd src && ./configure --with-realtime=uspace --enable-build-documentation && make clean && make -j$(nproc) && cd ..
+```
+
+## One-Time Setup
+
+For first-time setup on a fresh clone (8 numbered steps with checks, covering Debian verification, debian/control generation, build deps, runtime deps, configure script generation, build configuration, agent-helpers hook installation, realtime/setuid setup, and optional RT machine tuning): see [memory/reference_fork_setup.md](memory/reference_fork_setup.md).
+
+## Upstream PR prep
+
+To upstream a fix from fork `master` to `LinuxCNC/linuxcnc`, use the wrapper subcommand (not raw cherry-pick, not the helper script directly — the latter bypasses the auto-approval hook):
+
+```bash
+agent-helpers/safe-agent-action.sh upstream-pr-prep \
+    --commit <fork-sha> \
+    --branch <pr-branch-name> \
+    --message /tmp/upstream-commit-msg.txt \
+    --worktree /var/tmp/linuxcnc-pr-<branch> \
+    [--build] [--push] [--cleanup] [--dry-run]
+```
+
+The wrapper dispatches to `agent-helpers/upstream-pr-prep.sh`. The script uses `git worktree` (not `git switch -c`, which would wipe `agent-helpers/` from the main working tree) so the main fork tree stays intact, dynamically resolves the GitHub-noreply author via `gh api user`, and verifies the cherry-picked diff against `upstream/master`. Prerequisites: `gh auth login`, `jq`.
+
+**Full procedure, prerequisites, workflow notes (worktree rationale, message handling, build flags, why `travis-install-build-deps.sh` is forbidden), and worked example (PR #3933):** see [memory/reference_upstream_pr_workflow.md](memory/reference_upstream_pr_workflow.md).
+
+## Gotchas
+
+- `apt-get build-dep .` only installs build deps — runtime deps (e.g., `python3-qtpy`) must be installed separately for run-in-place. New deps added in 2.10 won't be present from a 2.9.8 system install.
+- **Run latest build requires `rip-environment`** — without sourcing `scripts/rip-environment`, the system-installed LinuxCNC runs instead of the source build. The `linuxcnc` launcher auto-sources it, but bare commands like `halcmd`, `halrun`, `runtests` need it explicitly.
+- **`DISPLAY=:0` required** — `linuxcnc` without an INI opens a Tk GUI picker.
+
+## Environment
+
+- OS: Debian Trixie (13), Python 3.13, PREEMPT_RT kernel
+- LinuxCNC version: 2.10.0~pre1
+- Build mode: run-in-place (RIP), uspace

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

MEMORY.md

@@ -0,0 +1,6 @@
+# linuxcnc memory index
+
+- [Fork one-time setup](memory/reference_fork_setup.md) — 8-step setup procedure for a fresh clone (Debian, debian/control, build/runtime deps, configure, agent-helpers hooks, setuid, RT tuning)
+- [Upstream PR workflow](memory/reference_upstream_pr_workflow.md) — full procedure for `agent-helpers/upstream-pr-prep.sh`, prerequisites, worktree rationale, build-flag CI parity, worked example PR #3933
+- [Teleop velocity leak](memory/reference_teleop_velocity_bug.md) — upstream `axis_sync_teleop_tp_to_carte_pos` doesn't reset `curr_vel`/`curr_acc`; post-homing drift; fork master commit `f40e8e64bc`, upstream PR #3933
+- [Public fork hygiene](memory/feedback_public_fork.md) — never reference private repo names, paths, or links from any committed file in this fork

TODO.md

@@ -0,0 +1,3 @@
+# TODO
+
+*(no pending items)*