docs: post-v0.6 sync — audit-log security invariants, refusal UX, threat model

`/document-release` sweep over the v0.6 ship (PRs #178 + #184). The
audit-log architecture doc, CLI reference, undo/redo user guide,
and the security page all had drift relative to what shipped — the
six codex passes + Claude code-review pass + security review added
behaviors that the docs hadn't caught up to.

Updates:

  - `docs/src/architecture/audit-log.md`: new
    "Security invariants" section documenting the path allowlist
    (#183), degraded-log refusal (#170), and tail-ID stalecheck
    (#165/#171). Also bumped the stale `claude_scope_version`
    example from 0.3.0 to 0.6.0 in the record-shape snippet.
  - `docs/src/security.md`: new "Threat model" section covering
    hostile audit-log entries (linking to the allowlist invariants)
    and hand-edited settings files (linking to atomic-writes), plus
    explicit out-of-scope items (multi-user systems, resource
    exhaustion, binary tampering).
  - `docs/src/user-guide/undo-redo.md`: documented the three new
    user-visible refusals — the "log degraded" tooltip / button
    disable, the "log changed since the preview" staleness error,
    and the "path injection refused" hostile-record message.
  - `docs/src/reference/cli.md`: new "Refusals" subsection covering
    the same three error states for `undo` / `redo` / `restore`,
    including the explicit note that `--yes` does not bypass any of
    them.

README.md already had v0.6 feature coverage (audit log bullet +
keybindings table entry) from earlier commits; no further edits.

No source-code TODOs are stale — the audit/restore code is comment-
dense but every comment names a live invariant.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bminier

docs/src/architecture/audit-log.md

@@ -36,7 +36,7 @@ record valid.
   },
   "path": ["permissions", "allow", 0],
   "to_kind": null,                   // set on change-kind ops
-  "claude_scope_version": "0.3.0"
+  "claude_scope_version": "0.6.0"
 }
 ```
 
@@ -166,6 +166,45 @@ to a point that lives in an archive works the same way as restoring
 to a point in the active log — same `record_sides` walk, same per-
 file snapshot revert.
 
+## Security invariants
+
+The audit log is read by every undo / redo / restore call, and its
+contents drive direct writes to the user's settings files. A hostile
+line appended to `audit.jsonl` (cloud-sync collision, malicious
+postinstall, compromised tool with user-scope write) must not be able
+to escalate into arbitrary file-write. Three gates enforce that.
+
+**Path allowlist (#183).** Every audit-log boundary —
+`undo_redo_target`, `restore_to_point_preview`,
+`apply_restore_to_point`, and the CLI's `cmd_undo` / `cmd_redo` /
+`cmd_restore` — calls `validate_audit_records` immediately after
+reading records and before building any `RestorePlan`. Each
+`Side.file_path` must equal one of the four resolved `ScopePaths`
+slots (`local`, `project`, `user_local`, `user`) for that record's
+own `project_dir`, against the active home override. Canonicalization
+absorbs platform-specific path forms (`/var → /private/var` on macOS,
+`\\?\C:\…` extended-length paths on Windows). The basename must be
+`settings.json` or `settings.local.json`. Any path outside the
+allowlist is refused with a clear `path injection refused` message;
+no writes happen.
+
+**Degraded-log refusal (#170).** `audit::read_all` reports a count
+of unreadable lines (corrupt JSON, schema drift the reader can't
+parse, truncated tails). Every undo / redo / restore path gates on
+that count: the GUI's `require_clean_audit_log` and the CLI's
+`read_audit_log` both refuse with a non-zero exit / blocked topbar
+button when `skipped > 0`. A partial log could leave the undo/redo
+state machine pointing at an op that was already undone, and
+confirming would emit a duplicate `restore` entry.
+
+**Tail-ID stalecheck (#165, #171).** Every restore re-reads the log
+immediately before applying and compares the trailing record's ULID
+against the value captured at preview time. A mismatch means the log
+changed under the user — refuse rather than apply a plan against a
+log the user didn't see. This catches concurrent GUI/CLI appends in
+the prompt window AND the (smaller) window between the initial read
+and `--yes` apply.
+
 ## Sandbox
 
 When `--home` is set, `emit_audit` skips the rotation + append

docs/src/reference/cli.md

@@ -137,3 +137,26 @@ For `undo` / `redo` / `restore`, `--json` emits the `RestorePreview`
 for a `--dry-run` and the resulting `restore` entry (as an
 `AuditRecordView`, the same shape `history --json` produces) once
 applied.
+
+### Refusals
+
+`undo` / `redo` / `restore` exit non-zero with a clear message and
+write nothing in these cases:
+
+- **`N audit-log entries are unreadable — refusing to compute
+  undo/redo against a partial log.`** The audit log has malformed
+  lines that the reader skipped. Acting against a partial log could
+  emit a duplicate restore entry; repair the log (copy aside, drop
+  the broken lines) and retry.
+- **`the audit log changed since the plan was built` /
+  `the audit log changed while waiting for confirmation`.** A
+  concurrent CLI or GUI session appended to the log between this
+  command's plan-build and apply (or during the confirm prompt). The
+  stale plan is rejected; re-run the command against the fresh log.
+- **`path injection refused`.** An entry's `file_path` points outside
+  the legitimate scope set for its `project_dir`. Indicates the log
+  has been hand-edited or corrupted by a third party; do not apply.
+  See the [security threat model](../security.md#threat-model).
+
+These refusals apply equally under `--yes` — there is no path that
+silently writes to the wrong file.

docs/src/security.md

@@ -61,3 +61,44 @@ tomorrow with no code change on our end.
   documented at [Architecture → Audit log](./architecture/audit-log.md).
 - The docs site (this one) has **no analytics**. No tracking
   pixels, no third-party scripts.
+
+## Threat model
+
+ClaudeScope is a single-user desktop tool. The user running the app
+is the only legitimate operator. Within that frame, two threat
+surfaces are explicitly defended:
+
+**Hostile audit-log entries.** An attacker who can append a line to
+`~/.claude/claude-scope/audit.jsonl` (cloud-sync collision from a
+compromised peer, a previously-compromised tool with user-scope
+write, a malicious package postinstall, a shared workstation) should
+not be able to escalate that capability. The audit log drives
+`apply_restore_plan` to write to files at paths recorded in the log
+itself — without defenses, one well-formed line could direct
+ClaudeScope to write attacker-controlled JSON to any path the user
+can write to. The
+[Architecture → Audit log § Security invariants](./architecture/audit-log.md#security-invariants)
+section documents the three gates (path allowlist, degraded-log
+refusal, tail-ID stalecheck) that enforce containment. The path
+allowlist is the load-bearing control: every `Side.file_path` is
+validated against the four legitimate `ScopePaths` for its
+`project_dir` before any write happens.
+
+**Hand-edited settings files.** Users (or other tools) may edit
+`settings.json` outside ClaudeScope at any time. The atomic-write
+path captures a `FileStamp` at load time and refuses the save when
+the stamp differs at persist time — the user's external edit
+survives. See
+[Architecture → Atomic writes](./architecture/atomic-writes.md) for
+the contract.
+
+Out of scope:
+
+- Multi-user systems with adversarial co-users. The threat model
+  assumes a single trusted user; on shared workstations, OS-level
+  ACLs are the right layer.
+- Resource-exhaustion attacks. A user who can write large amounts
+  of data into `audit.jsonl` can fill the disk; that's a property
+  of any append-only log, not a ClaudeScope-specific issue.
+- Tampering with the bundled binary. Binary integrity is the
+  installer / OS package manager's responsibility.

docs/src/user-guide/undo-redo.md

@@ -69,6 +69,28 @@ captured. If the file was hand-edited since (so its current contents
 differ from what the log expected), the confirm modal shows a warning
 band — you can still proceed, but you'll be overwriting that edit.
 
+**Disabled with a "log degraded" tooltip.** If
+`~/.claude/claude-scope/audit.jsonl` has unreadable lines (corrupt
+JSON, a crash mid-write, schema drift the build doesn't recognize),
+both Undo and Redo are withheld until the log is repaired. The
+tooltip names the count of unreadable entries. Acting against a
+partial log could emit a duplicate restore entry, so ClaudeScope
+refuses rather than guess. The CLI exits non-zero with the same
+message. Repair option: copy `audit.jsonl` aside, drop the broken
+lines, restart.
+
+**"Log changed since the preview."** If a concurrent CLI or GUI
+session writes to the audit log while the confirm modal is open,
+the apply is refused with that message — re-open the History view
+and retry against the fresh state. Same posture under
+`claude-scope-cli undo` and `--yes`.
+
+**"Path injection refused."** If an audit-log entry's `file_path`
+points outside the legitimate scope set for its project (e.g. an
+attacker hand-wrote a hostile line into `audit.jsonl`), the restore
+is refused before any I/O. See the
+[Security threat model](../security.md#threat-model) for context.
+
 ## Restore to before an entry
 
 Single-step undo walks back one operation at a time. To jump back