Cornerstone CLI — `status` Command Internals

Implements: ADR-0016 — Cornerstone Status Command Source: tools/cornerstone.py

Purpose

The cornerstone status command answers one question before an agentic session begins:

"Is this project's infrastructure fully configured and reachable?"

It aggregates four orthogonal readiness checks into a single pass/fail verdict. A failing check surfaces the gap before an agent starts, preventing cryptic mid-session failures.

The Four Checks

1. Environment (`_check_env`)

Reads the project-root .env file and verifies that every key listed in REQUIRED_ENV_KEYS (AGENTIC_TELEMETRY_URL, SQUIT_API_KEY) is present.

Why presence-only validation? Value validation (e.g., "is this URL reachable?") is the job of the service that consumes the variable — not a general-purpose CLI. Validating format here would add coupling without adding safety.

Why not python-dotenv? The tool must run before any pip install. A bespoke six-line parser covers the 99 % case (KEY=value lines, # comments) without adding a dependency.

2. Observability Service (`_check_observability`)

Issues an HTTP GET to {AGENTIC_TELEMETRY_URL}/healthz with a 5-second timeout and expects HTTP 200.

Why /healthz and not a TCP ping? A TCP connection proves the host is reachable; it says nothing about whether the application is running. /healthz is a standardised, lightweight endpoint that exercises the application layer and confirms the service can accept requests from the agent's network context.

URL resolution order: 1. .env file (preferred — repo-local configuration) 2. Process environment variable (fallback — allows CI pipelines to inject the URL as a secret without a committed .env)

3. GitHub Auth (`_check_github_auth`)

Runs gh auth status and checks for exit code 0.

Why gh CLI and not the REST API? Agents issue gh pr create, gh issue comment, etc. — they use the gh binary's credential store, not a raw GITHUB_TOKEN env var. We need to validate the binary's own authenticated state, not merely that a token exists somewhere in the environment.

4. Agent Skills Sync (`_check_skills_sync`)

Checks that .agents/.last_sync exists and its mtime is within the last 24 hours (SYNC_MAX_AGE_HOURS).

Why mtime as a freshness signal? The sync process touches .last_sync as its final step. The file acts as a cheap, reliable sentinel — no structured log parsing required. Any sync implementation (rsync, git subtree, custom CI step) can honour the contract by touching this file.

Why 24 hours? Short enough to ensure agents run with skills that include recent policy fixes; long enough that daily developer sessions don't require a sync before every git commit.

Orchestration Strategy

All four checks always run — there is no short-circuit on the first failure. This is deliberate: cornerstone status should give operators a complete picture in a single invocation, not just the first problem.

checks: dict[str, bool] = {
    "environment": _check_env(base_dir),
    "observability_service": _check_observability(base_dir),
    "github_auth": _check_github_auth(),
    "skills_sync": _check_skills_sync(base_dir),
}

Output Modes

Mode	Flag	Format	Use case
Human	(default)	`✓ / ✗` per check	Interactive terminal
Machine	`--json`	`{"status": "healthy"\\|"unhealthy", "checks": {...}}`	CI step consuming the result

The JSON contract is stable — new checks are added to the checks dict without changing the top-level status field semantics.

Adding a New Check

Write a _check_<name>(base_dir: str = ".") -> bool function.
Add an entry to the checks dict in check_status.
Add a print line in the human-output block.
Update ADR-0016 to document the new check's contract.

Cornerstone CLI — status Command Internals