CLAUDE.md git:20260927.292d20eA

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

# cub-scout

GitOps explorer for agents: a read-only Kubernetes observer. Detects ownership (Flux, ArgoCD, Sveltos, Modelplane, Helm, Crossplane, kro, ConfigHub, Native).

## Read First

For a fresh coding session in this repo, read these in order:

1. [AI-README-FIRST.md](AI-README-FIRST.md)
2. [HANDOVER.md](HANDOVER.md)
3. [docs/reference/commands.md](docs/reference/commands.md)
4. [docs/reference/cli-contract.md](docs/reference/cli-contract.md)
5. [docs/reference/json-contracts.md](docs/reference/json-contracts.md)

## Related Abilities

- `cub-scout`: read-only cluster/GitOps observation, connected comparison, import preview, MCP serving
- `cub`: ConfigHub CLI for intended-state workflows, spaces/units/targets, `cub variant upload`
- `confighub/sdk`: renderer/bridge implementation detail used by `cub`

Important boundary:
- `cub-scout import --git-path` is a local structure/import-preview flow
- `cub variant upload` ingests **already rendered** resources (a directory, `-`,
  or an `oci://` bundle) and makes a space's units match them; the rendering is
  done by your own tooling (`helm template`, `kustomize build`, an installer)
- `cub gitops discover` and `cub gitops import` **no longer exist**: cub removed
  the whole `gitops` group in July 2026, and nothing replaced the render-target
  model (#573)
- do not claim that `cub-scout` can do SDK renderer work unless current code/help exposes it

## Build & Run

```bash
go build ./cmd/cub-scout
./cub-scout map              # Interactive TUI
./cub-scout map list         # Plain text
./cub-scout trace deploy/x -n y
./cub-scout scan
./cub-scout gitops status    # GitOps pipeline health (v0.14)
./cub-scout graph export     # Resource graph (v0.6)
./cub-scout patterns detect  # Pattern detection (v0.7)
```

**Always use `./cub-scout`** (local binary), not `cub-scout`.

**Output formats (v0.14):** Most commands support `--format ascii|json|md`.

## Claude Capability-Assistant Mode

For demo flow "Can I do X with cub-scout or ConfigHub?":

- Start from [AI-README-FIRST.md](AI-README-FIRST.md) for current tool boundaries and issue queue.
- Start from shared skill profile: [skills/cub-scout/SKILL.md](skills/cub-scout/SKILL.md)
- Use [docs/howto/claude-capability-assistant.md](docs/howto/claude-capability-assistant.md) as the operating playbook.
- If a request is not currently supported, file using:
  - `./scripts/create-ai-capability-issue.sh ...`
  - or issue template: `AI capability gap`

## Documentation

| File | Purpose |
|------|---------|
| [README.md](README.md) | Project overview, install, quick start |
| [CLI-GUIDE.md](CLI-GUIDE.md) | Workflow-first CLI guide |
| [docs/reference/cli-reference.md](docs/reference/cli-reference.md) | Complete command catalog (A-Z) |
| [docs/reference/commands.md](docs/reference/commands.md) | Detailed command usage and examples |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
| [docs/semantic-contract.md](docs/semantic-contract.md) | ASCII vs JSON meaning contract (R1-R6) |
| [evals/README.md](evals/README.md) | Agent evals: running, recording, and growing the suite |

## Key Principles

1. **Single cluster** — standalone mode inspects one kubectl context; multi-cluster only via connected mode
2. **Read-only by default** — never modifies cluster state
3. **Deterministic** — same input = same output, no AI/ML
4. **Parse, don't guess** — ownership from actual labels, not heuristics
5. **Complement GitOps** — works alongside Flux, Argo, Sveltos, Modelplane, Helm
6. **Graceful degradation** — works without cluster, ConfigHub, or internet
7. **Test everything** — `go test ./...` must pass
8. **CLI/TUI parity** — CLI and TUI are two renderings of one model. Every feature must have both a CLI command (with `--format ascii|json|md`) and a TUI equivalent. CLI is not a second-class citizen.
9. **Measured for agents** — agents are the primary users of cub-scout's evidence. Claims that cub-scout helps an agent cite the agent evals ([evals/README.md](evals/README.md)), with and without cub-scout on the same evidence; where it adds nothing, say so. An *agentic* GitOps explorer is one that gives agents a cost and time advantage (cost per correct answer, turns, seconds), not only better answers; claim it only where the evals show it.

## Current Milestone Reality

Use [HANDOVER.md](HANDOVER.md) as the latest execution snapshot.

As of the current handover:
- the Argo truth-and-guidance track is closed (`#365`, `#366`, `#367`)
- the Git import parser track is complete through ApplicationSet generator support (`#363`)
- `#369` is shipped: `doctor` is now the first standalone MCP troubleshooting tool
- `#364` is investigated, not a mandate to merge `cub-scout` with cub's import path
- the highest-leverage open queue is now `#370`, then `#368`

## Directory Structure

| Path | Purpose |
|------|---------|
| `cmd/cub-scout/` | CLI commands, TUI |
| `pkg/agent/` | K8s watcher, ownership detection |
| `test/` | Tests |

## Ownership Detection

| Owner | Detection |
|-------|-----------|
| Flux | `kustomize.toolkit.fluxcd.io/*` or `helm.toolkit.fluxcd.io/*` labels |
| ArgoCD | `argocd.argoproj.io/instance` label or tracking-id annotation |
| Sveltos | `projectsveltos.io/owner-kind` + `projectsveltos.io/owner-name` annotations, Sveltos ownerRef, or Sveltos API group |
| Modelplane | `modelplane.ai` / `infrastructure.modelplane.ai` API groups, Modelplane identity labels, or Modelplane ownerRef |
| Helm | `app.kubernetes.io/managed-by: Helm` |
| Terraform | `app.terraform.io/run-id` annotation or managed label |
| Crossplane | `crossplane.io/claim-name` label *(experimental)* |
| kro | `kro.run/*` labels/annotations, kro ownerRef, or kro API group |
| ConfigHub | `confighub.com/UnitSlug` label |
| Native | None of the above |

## Testing

```bash
go build ./cmd/cub-scout
go test ./...
```

## Backlog Tracking

Future ideas live in supplemental planning docs (`docs/roadmap-*.md`, `docs/reference/*-product-guide.md`).
These are non-authoritative and easy to forget during sprint planning.

Rules:
- `docs/roadmap.md` contains an **Untracked Backlog Checklist** at the top
- When a new idea appears in any planning doc, add it to the checklist
- When an item graduates to real work, file a GitHub issue and remove the checklist entry
- The master tracking issue is **#154** — keep it current

This prevents ideas from being trapped in prose nobody re-reads.

---

## Pre-Coding Test & Success Proof Requirements

All feature and bugfix issues **must define success before implementation**.

### 1. Deterministic Unit Tests (Required)
- Define exact inputs (fixtures, manifests, objects)
- Define expected outputs (ownership classification, lineage graph, buckets)
- Tests must be: order-independent, K8s-version tolerant, runnable without live cluster

### 2. Example / Full Test Coverage (Required for user-visible behavior)
- Add or extend an example under `examples/`
- Or explicitly reference an existing example it validates against
- Examples serve as: regression protection, documentation, demo artifacts

### 3. E2E / Integration Proof (Required unless explicitly waived)
For features affecting real cluster behavior, define validation in:
- Standalone mode (single cluster, kubectl context)
- Connected mode (mocked or recorded if CI cannot auth)
- Fleet mode (if behavior aggregates across clusters)

If E2E cannot run in CI: provide reproducible local script or contract test with recorded inputs/outputs.

### 4. Graceful Degradation Rules (Required)
Each issue must state:
- What happens when metadata is missing
- How partial results are surfaced
- How false "unmanaged/orphan" states are avoided

### 5. Agent Eval Case (Required for agent-facing behavior)
A change to MCP tool output, a skill, or a new kind of evidence an agent should use:
- Adds or updates an eval case under `evals/` that asks the question it answers
- Re-records the fixtures in the same PR when tool output changes
- An agent-facing bug fix adds a case that fails without the fix

See [evals/README.md](evals/README.md#growing-the-suite). Eval scoring runs on recordings, never a live cluster.

### 6. Definition of Done
An issue is complete only when:
- Tests exist and pass
- Examples demonstrate expected behavior
- User-facing output is correct **and explainable**
- Agent-facing changes have an eval case, and its result is known

---

## cub-scout v0.5 Delivery Addendum

Historical note: the remainder of this file preserves older delivery-phase rules.
Current execution priority and milestone state live in [AI-README-FIRST.md](AI-README-FIRST.md) and [HANDOVER.md](HANDOVER.md).

This addendum defines how the principles in this document are applied during the
**v0.5 delivery phase**.

v0.5 is a **trust and utility milestone**, not a completeness milestone.

The goal is to ship a version that users can rely on daily, with clearly bounded
capabilities and explicitly documented limitations.

---

## v0.5 Priorities (In Order)

During v0.5 delivery, decisions MUST be evaluated against these priorities,
in descending order:

1. **Correctness of ownership and provenance**
   - cub-scout must not make false claims about where resources came from.
   - Unknown or ambiguous states are always preferable to incorrect certainty.

2. **Honest, explainable output**
   - Partial results are acceptable if clearly explained.
   - Errors must explain what failed and why, not just that something failed.

3. **Stability of the TUI and CLI**
   - No panics, crashes, or undefined navigation behavior.
   - Predictable keybindings and command behavior.

4. **Scope discipline**
   - Features that dilute trust or stability are out of scope.
   - v0.5 is intentionally narrow.

Completeness, performance optimizations, and breadth of controller support are
explicitly secondary during this phase.

---

## Core Principles (Never Waived)

The following principles are non-negotiable for v0.5:

- Deterministic behavior
- Parse, don't guess
- Read-only by default
- No AI/ML inference
- Avoid false ownership or orphan claims
- Graceful degradation in the presence of missing or partial data

Any change that violates these principles MUST NOT ship.

---

## Strong Defaults (May Be Deferred with Explicit Waiver)

The following expectations remain strong defaults but may be deferred for v0.5
*only if a waiver is explicitly recorded*:

- Full end-to-end (E2E) test coverage
- Exhaustive controller support
- Complete example coverage for all edge cases
- Fleet-scale or connected-mode parity

Deferral is acceptable only when the failure mode is safe and documented.

---

## Waivers (v0.5 Only)

A requirement may be waived during v0.5 delivery **only if all conditions below
are met**:

1. The limitation is clearly documented (code comment, issue, or docs).
2. The failure mode is safe:
   - No false positives
   - No misleading ownership or health claims
3. A follow-up issue is filed and labeled appropriately.

Waivers MUST be visible and intentional.
Silent corner-cutting is not acceptable.

---

## Testing Expectations for v0.5

For v0.5:

- Logic affecting ownership, provenance, or reconciliation reasoning MUST have
  deterministic tests.
- UI and CLI changes MUST be exercised against at least one real cluster.
- E2E tests are strongly encouraged but may be deferred via waiver.

The absence of a test is acceptable only if:
- The behavior is explicitly documented as provisional, AND
- The risk surface is understood and bounded.

---

## Release Bar for v0.5

v0.5 is considered shippable only if:

- Ownership claims are reproducible and conservative.
- The TUI does not panic on malformed or minimal clusters.
- Known limitations are explicitly documented.
- The tool can be recommended to another operator with clear caveats.

---

## Post–v0.5 Expectation

This addendum is temporary.

Future releases may:
- Remove waiver allowances
- Tighten testing requirements
- Raise the completeness bar

All work done under v0.5 constraints should assume later hardening.