CLAUDE.md git:20260625.6826d79A

Immutable. This exact content never changes and is served at /api/v1/blob/dfb236a71d3f7bac.

# CLAUDE.md

Claude-specific operating guidance for AUV. `AGENTS.md` is authoritative;
this file is a short operating card for staying inside the current project
phase.

## Current Mode

AUV is now actively in the Minecraft spatial-substrate lane: MC-6 measurement
closure and MC-7 offline 3DGS data/export/consumer slices. The former
SkillBundle surface remains retired; do not reintroduce bundle execution,
export, or verification as compatibility. Do not treat one archived macOS AX
proof as the product center, and do not spend active roadmap budget polishing
the archived vertical.

Current validation boundary:

- One real macOS AX copilot vertical is proven and archived.
- That proof is specific to local TextEdit-style execution and remains a
  recoverable reference, not the current roadmap center.
- New work may extend AUV through the approved spatial-substrate lane described
  in `docs/ai/references/2026-06-18-auv-mc5-onward-execution-plan.md`,
  especially the owner-opened MC-7 offline 3DGS path and its downstream
  consumers.
- Core-lane stabilization work may continue in parallel, but this document now
  treats it as a separate convergence lane rather than the active exploration
  center.

Convergence evidence:

- The archived AX copilot proof lives in
  `docs/archive/verticals/ax-copilot/2026-06-09-auv-macos-ax-copilot-mvp-evidence-pack.md`.
- The active execution boundary for this phase is
  `docs/ai/references/2026-06-18-auv-mc5-onward-execution-plan.md`.
- The owner-opened 3DGS design note lives in
  `docs/ai/references/2026-06-18-minecraft-mc7-offline-3dgs-inspect-artifact-design.md`.
- The current MC-7 downstream chain now reaches:
  `scene packet -> training package -> training launch prep -> remote job envelope -> remote result collection`.

Current MC-7 closure boundary:

- D2: accepted-only scene-packet inspect output.
- D3: training-package export plus Nerfstudio compatibility view.
- D4: read-side inspect consumer for training-package artifacts.
- D5: training-launch preparation and readiness consumer.
- D6: remote training job envelope and blocked-evidence closure.
- D7: remote training result collection and evidence closure.
- Do not claim trainer quality, splat usefulness, or real-source restored
  validation from D5-D7. Those slices only prove the data and job/result
  surfaces close honestly.

Current seam to preserve:

```text
recognition / AX / candidates
  -> ActionResolver
  -> auv-driver InputActionResult
  -> OperationResult / VerificationResult / trace artifacts
```

`auv-overlay-macos` is visual-only presentation. `auv-driver` /
`auv-driver-macos` own input delivery and disturbance reporting. Do not create
a third action-result schema beside `ActionResolverDecision` and
`InputActionResult`. `candidate_promotion` remains part of AUV core as a
reusable promotion/gating seam even while `candidate-action` is frozen.

## Start Every Task By Classifying It

Use one label before editing:

- `bug fix`: a reproduced defect with a narrow fix and regression test.
- `test-only`: coverage for existing behavior.
- `docs-only`: clarification with no runtime behavior change.
- `narrow refactor`: behavior-preserving cleanup required by the assigned slice.
- `approved feature`: owner named or approved the behavior/module to add.
- `substrate research`: owner-approved exploration of 3D spatial grounding,
  offline 3DGS inspect artifacts, or next-generation verification evidence.

If the task does not fit one label, ask for a smaller slice.

## Scope Defaults

- Work on one focused outcome. Multi-file changes are fine only when the files
  are part of the same approved dependency chain.
- Do not chase TODOs, roadmap notes, or future APIs unless the owner names that
  slice.
- Do not add drive-by renames, helper extraction, comment polish, or unrelated
  compatibility fallbacks while touching code.
- New durable public namespaces, traits, modules, commands, or contract fields
  need owner-approved design. Private helpers are fine when they serve the
  current slice and have narrow tests.
- Cross-layer changes need an explicit dependency direction, for example:
  `contract -> driver artifact -> read-side inspector test`.

## Rust Working Bias

- When RustRover MCP is available, use it as the primary structured layer for
  Rust code work: symbol lookup, definition inspection, call analysis,
  diagnostics, and IDE-backed validation.
- Use plain text search mainly for non-structural materials: docs, logs,
  fixtures, JSON artifacts, comments, and literal strings.
- For Rust changes, do not grep first unless semantic lookup failed or the
  target is a literal-text CLI/document surface.

## Approval Boundary

Approved:

- The owner named the function, module, behavior, or document to change.
- The owner accepted a concrete proposal.
- The owner asked for one specific next slice.

Not approved:

- A doc or TODO mentions a future feature.
- The change follows naturally from the previous slice.
- The repo scan found a smell.
- The owner said "you decide" without naming a chain of follow-ups. Treat that
  as one focused slice, then stop.

## Completion Behavior

After a slice:

1. State what changed and what was validated.
2. List follow-up candidates as observations, not as already-started work.
3. Stop and wait for the owner to choose.

Do not chain into the next slice without explicit confirmation.

## Validation

For behavior changes, run:

- `cargo fmt --check`
- `cargo check`
- `cargo test`
- `git diff --check`

Also run command-list smoke checks when command catalog, runtime frontends, or
CLI behavior changes. Docs-only edits can skip Cargo validation, but say so in
the summary.