Base diagnostics and recon

Base diagnostics is Guard’s repository-orientation workflow. It resolves the exact repository and current commit, builds a shallow evidence map, and saves context that makes later audit and improvement work more accurate.

What base diagnostics answers

Base diagnostics answers: “What repository is this, how is it organized, and which surfaces deserve deeper inspection?” It does not answer whether the project is secure, well tested, dependency-safe, or ready for autonomous change.

The underlying recon runbook is analysis-only. It must not create issues, branches, commits, pull requests, tags, or fixes. It also does not publish a score-bearing audit metric. The product may show a completed state, stack, structural signals, and a report, but those are orientation rather than a health grade.

This distinction matters because a tidy repository map can coexist with a critical vulnerability or unreliable tests. Deeper audits own those conclusions.

What recon inspects

Recon keeps its pass broad and intentionally shallow. It collects representative evidence from:

• repository provider, complete path, default branch, and audited commit;
• top-level layout and important directories;
• primary languages, frameworks, manifests, workspaces, and runtime hints;
• application boundaries and deterministic routes where they can be established;
• README, contributor guidance, project documentation, and agent instructions;
• test layout, test configuration, and obvious verification commands;
• CI, deployment, container, and automation files;
• repository cleanliness, generated output, large artifacts, and checked-in build residue;
• representative security, dependency, configuration, and maintainability signals;
• whether a safe build or test probe is feasible within the run’s constraints.

Recon does not build a complete dependency inventory, prove every route, run a full vulnerability scan, or replace any published audit. When dynamic routing or an unsupported ecosystem prevents a deterministic answer, it records that limitation instead of guessing.

The workflow also reads repository-root Guard instructions when present and preserves an internal handoff summary. Later agents can use this shared project context without requiring the product UI to expose internal operational notes.

What recon produces

A successful run saves two Upfront-facing artifacts:

• a typed JSON summary for the repository map and base-diagnostics card;
• a Markdown report with repository identity, revision, structure, evidence, and limitations.

It may also save useful repository or website links. Separately, it updates a project-scoped internal recon context for later Fleet work. That internal artifact is versioned and is not a public report.

The visible product can show stack information, readiness signals, a component map, a narrative, and the full report when available. Treat the audited commit in the report as the boundary of the observation. New commits require a rerun when current orientation matters.

Failure and unknown evidence

Recon requires an exact provider repository path and usable repository access. It fails when the target is missing or ambiguous, remote reachability fails, or the allowed shallow checkout cannot retrieve the repository.

On those failures, the workflow saves a diagnostic rather than an Upfront recon summary. It must not fabricate a repository map or mark base diagnostics complete merely to unlock other product cards.

Missing evidence remains explicit in successful runs as well. For example, dynamic routes may be noted without a complete route list, and a build probe may be skipped when it would be unsafe or unsupported. These limitations tell later audits what they still need to establish.

Use Repository is unavailable when the exact target cannot be read and A run is stuck or failed when execution stops after access succeeds.

Relationship to audits

Recon provides shared orientation; each audit independently gathers the evidence needed for its own question and score. An audit must not inherit an unsupported “healthy” conclusion from recon.

After base diagnostics, open the published audit cards and read their current reports. Audits, scores, and evidence explains how those results differ from the repository map.