gitguard: anchor linked-worktree baselines on core.worktree/core.bare, not the shared config inode (vogt WI-1670)

.github/workflows/ci.yml

@@ -8,24 +8,45 @@ on:
 permissions:
   contents: read
 
+# The layers are described in docs/testing.md. Everything here is hermetic: no
+# credential, no network beyond module download. The live-model layers
+# (scripts/smoke.sh, scripts/torture.sh) are run by hand.
 jobs:
-  build-test:
+  static:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-
       - uses: actions/setup-go@v5
         with:
           go-version: '1.26'
           check-latest: true
           cache: true
-
       # Pure Go: the build must stay CGO_ENABLED=0-clean (no cgo, no system libs).
-      - name: Build
-        run: CGO_ENABLED=0 go build ./...
+      - name: gofmt, vet, build
+        run: make static
 
-      - name: Vet
-        run: go vet ./...
+  unit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26'
+          check-latest: true
+          cache: true
+      - name: Unit tests (race)
+        run: make unit
+      - name: Unit tests against a poisoned HOME
+        run: make hermetic
 
-      - name: Test
-        run: go test ./internal/... -count=1
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26'
+          check-latest: true
+          cache: true
+      - name: Binary against a scripted model
+        run: make e2e

.gitignore

@@ -15,3 +15,6 @@
 # does not need to be. See .mcp.json.example. Commit a secret-free team config
 # with `git add -f .mcp.json` if you want one.
 /.mcp.json
+
+# scripts/cover.sh output
+/coverage/

.mcp.json.example

@@ -3,7 +3,7 @@
     "gitea": {
       "command": "gitea-mcp",
       "args": ["-t", "stdio", "-r", "-S", "issue,pull_request,actions"],
-      "env": { "GITEA_HOST": "https://git.example.com" },
+      "env": { "GITEA_HOST": "${GITEA_HOST:-https://git.example.com}" },
       "readOnly": true
     },
     "third-party": {

CLAUDE.md

@@ -7,9 +7,15 @@ CLI agent that helps users with software engineering tasks.
 ```bash
 CGO_ENABLED=0 go install ./cmd/klaudia   # updates the `klaudia` on your PATH
 CGO_ENABLED=0 go build ./...             # compile check only — writes no binary
-go test ./internal/...
+go test ./internal/...                   # unit tests
+go test ./e2e/...                        # the binary against a scripted model
+make check                               # every hermetic layer — what CI runs
 ```
 
+Testing is layered (static, unit, hermetic, e2e, live); `docs/testing.md` says
+what each layer is for and where a new test belongs. Unit tests must not read
+the real `$HOME` — `make hermetic` runs them against a poisoned one.
+
 `go build ./...` with multiple packages compiles and *discards* the results: it
 is a build check, not an install. `go build ./cmd/klaudia` does write a binary,
 but into the working directory, not onto `$PATH`. Running `klaudia` after either
@@ -22,30 +28,56 @@ Use `go install` when you mean to try the change.
 - **api** - Provider abstraction: Anthropic client + OpenAI-compatible shim
 - **tools** - Local tool implementations
 - **browser** - Lazy headless-Chrome engine + web search
-- **permission** - Permission modes + allow/deny rules (a leaf package)
+- **permission** - The three permission modes (a leaf package)
 - **trust** - Zones, command/tool classification, session-scoped grants
 - **session** - Transcripts, resume, persisted compaction summaries
 - **compaction** - Context/history compression (micro + auto)
-- **mcp** - Model Context Protocol support
-- **subagent** - Built-in sub-agent types
-- **skill** - User-defined skills (`.klaudia/skills`)
+- **mcp** - Model Context Protocol client (2026-07-28) + form elicitation
+- **subagent** - Sub-agent types: built-in, and markdown-defined (`.klaudia/agents`)
+- **worktree** - Per-sub-agent git checkouts: seed, adopt, conflict reporting
+- **skill** - Bundled skills (`skill/bundled/*.md`) + user-defined skills (`.klaudia/skills`)
+- **hooks** - Lifecycle hooks: the four events, project-hook trust, execution
+- **gitguard** - Keeps an autonomous run (the goal loop) from discarding or staging uncommitted work it does not own
 - **memory** - Auto-memory store
 - **doctor** - `/doctor` environment diagnostics
+- **gitprobe** - Klaudia's own read-only git calls, guarded against repo config
 - **streamjson** - Bidirectional stream-json frontend
+- **acp** - Agent Client Protocol v1 agent (editor-driven sessions)
 - **tui** - Terminal UI (Bubble Tea)
 - **prompt** - Prompt construction
 - **cli** - CLI entry point and wiring
 - **native** - Pure-Go search / bash-parsing / PDF
+- **textsafe** - Cleaning text from files and servers before the model sees it
 - **sandbox** - Local / OS-confined / container Bash execution
 - **schema** - Type/schema definitions
 - **version** - Version info
 
+`e2e/` (outside `internal/`) holds the end-to-end tests. `internal/fakeapi` is
+the scripted Anthropic API they and the `internal/cli` tests share — test
+support, imported by nothing in the product.
+
 ## Design record
 
 `docs/ux-spec.md` is the authoritative record of the two terminal-UX specs and
 where the implementation deliberately differs from them — read it before
-"fixing" something that looks unimplemented. `docs/trust.md`, `docs/jobs.md` and
-`docs/working-tree.md` cover the three subsystems in detail.
+"fixing" something that looks unimplemented. `docs/trust.md`, `docs/jobs.md`,
+`docs/working-tree.md`, `docs/hooks.md` and `docs/acp.md` cover five subsystems
+in detail; `docs/embedding.md` is the versioned stream-json contract, and
+`docs/testing.md` covers the test layers.
+
+Hooks are the one subsystem that executes a string from a config file, so
+`docs/hooks.md` is where the reasoning for the trust prompt lives. A hook runs
+*after* the host gate, never instead of it: anything that lets a config file
+grant permission is a bug, not a feature request.
+
+There are three frontends — TUI, stream-json, ACP — and one contract between
+them: `agent.Turn`, applied by `Turn.Apply`. A new capability is a **field on
+`Turn`**, not another parameter on a per-frontend `RunFunc`; the per-frontend
+signatures are what let `AskUserQuestion` and `ExitPlanMode` sit dead over
+stream-json for months, because a frontend that omitted a capability was
+indistinguishable from one that did not want it. `docs/acp.md` records what the
+ACP frontend declines (client-side writes, `terminal/*`, `session/delete`) and
+why those are decisions rather than gaps.
 
 ## Rules
 

Makefile

@@ -0,0 +1,46 @@
+# Test layers — see docs/testing.md. `make check` is what CI runs.
+#
+#   static    gofmt, go vet, CGO_ENABLED=0 build
+#   unit      package tests under internal/ (race detector on)
+#   hermetic  unit tests again, against a poisoned HOME
+#   e2e       the real binary against a scripted model; no network, no credential
+#   smoke     the real binary against a live model (needs a credential)
+#   torture   the Phase 2 agent-loop torture test (credential, docker, python3)
+#
+#   cover     statement coverage of unit + e2e, merged, per package
+
+GO ?= go
+
+.PHONY: check static unit hermetic e2e smoke torture cover install
+
+check: static unit hermetic e2e
+
+static:
+	@out="$$(gofmt -l cmd internal e2e)"; if [ -n "$$out" ]; then echo "gofmt needed:"; echo "$$out"; exit 1; fi
+	$(GO) vet ./...
+	CGO_ENABLED=0 $(GO) build ./...
+
+# atexit_sleep_ms=0: a race-built binary sleeps 1s on exit by default, and the
+# lsp and mcp tests re-exec the test binary as a fake server — a second per
+# server stop, 3s for one mcp test. The sleep only helps report races in
+# goroutines still running at exit; the parent test binary still reports them.
+unit:
+	GORACE=atexit_sleep_ms=0 $(GO) test -race -count=1 ./internal/...
+
+hermetic:
+	scripts/hermetic.sh -count=1
+
+e2e:
+	$(GO) test -count=1 ./e2e/...
+
+smoke:
+	scripts/smoke.sh
+
+torture:
+	scripts/torture.sh
+
+cover:
+	scripts/cover.sh
+
+install:
+	CGO_ENABLED=0 $(GO) install ./cmd/klaudia