git:20260903.10f0277 to git:20260911.c655850

60 added, 76 removed. Audit A to A.

---

name: reality-check

- description: 'Compare a claimed state with observable repository evidence and report concrete gaps. Requires a claim or expected state to test. Triggers: "reality check", "is this claim actually done", "compare claim to repo".'

+ description: 'Check whether a claimed shipped feature, repo state or goal status holds up in evidence. Use when: comparing a claim with what exists; a gap report is not a verdict.'

practices: [design-by-contract, evidence-based-engineering]

hexagonal_role: domain

- consumes: [claim, repository-evidence]

- produces: [reality-check-report.v1]

+ consumes: [caller-question, native-source-evidence]

+ produces: [reality-check-report.v1, goal-measurement-report, native-status-snapshot]

context_rel:

- kind: supplier-to

with: plan

skill_api_version: 1

user-invocable: true

metadata:

tier: judgment

dependencies: []

- capabilities: [compare_claim_to_evidence]

- effects: [write_advisory_gap_report]

+ capabilities: [compare_claim_to_evidence, measure_declared_goals, report_native_status]

+ effects: [write_advisory_gap_report, write_goal_snapshot, write_requested_rendered_spec]

canonical_status: canonical

disposition: keep_strategy

- output_contract: reality-check-report.v1 JSON validated by skills/reality-check/scripts/validate-output.sh

+ output_contract: cited claim comparison; validated reality-check-report.v1 for durable gap reports; measured goal results or observable native status

---

# Reality Check

- Compare an explicit claim with observable evidence. Cite every confirmed or

- missing behavior with a file, command result, or artifact. Separate:

- - confirmed behavior;

- - concrete gap;

- - incomplete evidence;

- - changed assumptions.

- ## Prompt

- ```text

- Reality-check this claim: PR #1042 finishes the CLI regen migration,

- skills-codex/ generation now runs entirely through `ao gate check`, and

- `scripts/regen-all.sh` is deleted. Compare against agentops-wt/train2-c

- at HEAD. Cite file-by-file evidence for what's confirmed and what's

- still a gap.

- ```

- ## It's working if

- Observable in the trace, without reading the prose:

- - Every finding cites a file, command result, or artifact inside

- `.agents/scratch/reality-check/<run-id>/reality-check-report.json`.

- - A completion claim carries a disposition per stated goal, each one of

- `confirmed`, `concrete gap`, or `unverifiable`.

- - `skills/reality-check/scripts/validate-output.sh` accepts the report

- with no `verdict`, `readiness`, or `PASS` field present.

- - An untestable line is filed as `incomplete-evidence` with the missing

- artifact named.

+ Compare an expected state with observable evidence, measure declared goals, or

+ report native status. Select the requested question; a snapshot needs no

+ invented completion claim. Return facts and gaps without selecting work.

- ## Vision-coverage audit

+ ## Claim comparison

- When the claim is a completion or status claim, audit it against the stated

- goals, not against what happens to exist. Enumerate every goal in the vision,

- plan, or intent source and give each a disposition: confirmed with evidence,

- concrete gap, or unverifiable. The audit is complete only when every stated

- goal carries a disposition; full coverage of the built surface alone proves

- nothing about completion. The named failure mode is built-world bias:

- auditing only the code that exists, so goals nobody started never surface as

- gaps.

+ 1. Read the exact claim and its source. For a completion claim, enumerate every

+ stated goal, including work that was never started. Give each a disposition:

+ confirmed with evidence, concrete gap or unverifiable.

+ 2. Inspect relevant files, command outcomes and artifacts. Separate confirmed

+ behavior, concrete gaps, incomplete evidence and changed assumptions. Name the

+ missing evidence instead of resolving an untestable claim by assertion.

+ 3. Compare proposed scope with the original goal when asked about a plan. Report

+ additions that lack authority as scope escalation; the report cannot approve

+ them. Repeated measurements use the same question and criteria; a changed

+ question starts a different comparison.

+ 4. Return the cited findings with checked and not-checked scope. Keep native

+ tracker, Git, runtime, deterministic checks and semantic judgments distinct.

- ## Frozen question variants

+ A quick answer can be inline. A selected durable gap report retains

+ `reality-check-report.v1`: write `reality-check-report.json` under the caller's

+ chosen destination, default `.agents/scratch/reality-check/<run-id>/`, and run

+ `skills/reality-check/scripts/validate-output.sh <report.json>`. Include the

+ checked claim, evidence-backed finding kinds and goal-by-goal dispositions for

+ completion/status claims. This format permits no `verdict`, `readiness` or

+ `PASS` field; observations are not independent semantic judgment.

- When the same check runs across multiple passes or sessions, freeze the exact

- question wording before the first pass and ask it identically in every pass;

- record the frozen wording in the report. A pass that answers a reworded

- question starts a new baseline — comparing it against earlier passes is the

- drifting-rubric failure mode, and its answer does not count as a repeated

- measurement.

+ ## Goal measurement

- ## Ambition-escalation checkpoint

+ Inspect the declared goals source; prefer `GOALS.md` when it and legacy YAML

+ both exist. Preserve directive and gate identities and report each executable

+ check with its actual outcome. Run the requested `ao goals` command once:

+ `measure --json`, `validate --json`, `drift`, `history`, `export`, `meta --json`,

+ `scenarios` or `render`.

- When invoked during planning, compare the currently planned scope against the

- originally stated goal. Planned work that cannot be traced to a stated goal

- is reported as an escalation gap, exactly like a missing behavior. Reality

- Check reports the escalation; the caller decides whether the ambition or the

- stated goal changes.

+ These commands do not edit the goals source, but `measure`, `drift` and `export`

+ may write best-effort derived snapshots under `.agents/ao/goals/baselines/`.

+ `render --out <file>` writes a caller-selected spec; never target the goals

+ source or another non-derived file. Use stdout when no output file is requested.

+ Return command, exit code, goal-level results, aggregate measurement, missing

+ evidence and checked/not-checked scope. Do not add, remove, prioritize, migrate

+ or repair goals, or turn a measurement gap into assigned work.

- ## Output

+ ## Native status

- - **Artifact directory:** `.agents/scratch/reality-check/<run-id>/`.

- - **Filename:** `reality-check-report.json`.

- - **Format:** `reality-check-report.v1` JSON — the checked claim, one finding per

- confirmed behavior, concrete gap, incomplete-evidence item, or changed

- assumption (each with cited evidence), and, for a completion or status claim,

- the goal-by-goal coverage disposition. It carries no `verdict`, `readiness`, or

- `PASS` field; the validator rejects one.

- - **Validation command:**

- `skills/reality-check/scripts/validate-output.sh <reality-check-report.json>`.

+ Use `ao status` for the local evidence-store view. It validates content-addressed

+ intent and verdict artifacts before counting them, reports corruption or

+ unavailable sources, and shows evidence recency. Its durable stores are

+ `.agents/ao/intents/sha256` and `.agents/ao/verdicts/sha256`; a count is not a

+ per-artifact digest inventory. Inspect a specific digest or timestamp only when

+ that artifact is part of the requested question.

- If the claim cannot be tested against any observable evidence, report it as

- incomplete-evidence with the missing artifact named — never resolve an

- untestable claim as confirmed.

+ Report caller-supplied subject manifests from their named location. Otherwise

+ mark manifests, runtime phase, elapsed execution, tool-call activity and remaining

+ work as not checked. An artifact's recent timestamp proves evidence recency,

+ not an active worker. Read other tracker, Git or factory facts only from their

+ own authorized source; do not blend factory completion, green checks and a

+ fresh verdict into one health judgment. Report unavailable evidence explicitly.

## Boundary

- Return the report to the caller. Plan may use concrete gaps to refine the

- existing bead or caller intent. Reality Check reports observations; it does not

- mint a verdict or `PASS` of any version, create work, schedule, claim,

- implement, validate, retry, or deliver.

+ Return the selected report or snapshot. This skill neither changes native state

+ nor issues semantic PASS, repairs records, schedules or retries work. The

+ documented goal snapshots and requested report/spec writes are its only output

+ side effects. A native caller pursuing an authorized outcome uses these facts

+ and continues its work; the reporting mode does not decide completion for it.