AI readiness audit: how Guard measures whether agents can work without guessing

Can an agent deliver without rebuilding the context?

Guard asks: How ready is this repository for low-friction agent-led engineering? Readiness here is not typing speed, model choice, or the ability to produce a plausible patch. It is the quality of the path around the patch.

A low-friction path lets an agent understand product and technical context, choose a stable change, stay inside known boundaries, verify the result, and leave a usable handoff. This is not unsupervised work. It means the repository carries enough durable evidence for a person to spend attention on judgment instead of repeatedly reconstructing basic context.

An instruction file alone does not establish readiness, and a repository does not fail for lacking a named agent framework. Guard evaluates whether the current operating model connects task, context, implementation, verification, and handoff. The score summarizes that evidence without guaranteeing a future change or replacing human review.

What Guard can inspect without running the repository

Guard resolves one repository and fixes the audit to its default branch and full commit. It records the provider, complete repository path, available history, access level, and revision links when they can be established safely. That revision boundary is essential: readiness evidence can change when a command, plan, product rule, or agent instruction changes, even if application code does not.

The inventory then maps the repository shape, primary languages and frameworks, package managers, source and test roots, documentation, environment files, delivery anchors, and agent-facing surfaces. Generated output, dependency directories, caches, build artifacts, and similar machine-local material are ignored unless a tracked item there is directly relevant to a readiness or safety judgment. Websites linked beside the repository are outside this audit; they are not silently treated as another source of product truth.

Three kinds of context

• Technical context covers architecture and boundaries, contracts and models, established patterns, state transitions, dependencies, test strategy, runtime assumptions, safe extension points, and explicit forbidden actions.
• Product context covers purpose, users, workflows, domain language, business rules, expected behavior, current plans, acceptance criteria, and useful measures of success.
• Working-process context covers task intake, ownership, planning, repository entry, headless setup, local commands, environment rules, review, handoff, troubleshooting, release expectations, recovery, and project-specific habits.

Guard also maps machine-verification evidence, quality safeguards, persistent work memory, cross-agent entry points, skill and prompt assets, planning methods, and environment safety. A root GUARD.md, when present, can add evidence-consistent context. It cannot override the audit's scope, permissions, safety, language, or scoring rules, and its absence is neutral.

Where the audit deliberately stops

AI readiness is static and read-only. It reads the paths that describe how work should happen without claiming that those paths execute successfully. In particular, it does not:

• install dependencies or execute package-manager lifecycle commands;
• build the project, run tests, start services, or invoke repository scanners;
• create or modify code, documentation, issues, branches, commits, or pull requests;
• use production credentials, perform migrations, deploy, or mutate external systems;
• infer AI use or readiness from code style, commit wording, or generated-looking code;
• treat the absence of a named framework or instruction filename as a failure;
• turn missing CI/CD or branch-protection evidence into a complaint owned by this audit.

Existing CI, review, and release evidence can raise confidence when it is visible, but missing external gate evidence remains neutral here. The dedicated CI/CD audit owns the strength and enforcement of those controls. Likewise, a suspicious secret-like string is a prompt for careful interpretation, not proof of a leaked credential: examples, tests, fixtures, generated files, and explicit allowlists matter.

When the repository target is ambiguous, access fails, the commit cannot be resolved, the inventory needed for analysis is unavailable, or required reporting evidence cannot be produced, Guard stops with a diagnostic result. It does not manufacture an empty report, a synthetic zero, or an “N/A” score that looks like a completed audit.

How the evidence pass works

The audit separates discovery from judgment so one conspicuous file cannot dominate the result. The evidence pass follows a fixed order.

1. 1

   Resolve and inventory the exact revision

   Guard establishes repository identity, records the full commit, maps project shape, and locates documentation, verification, delivery, environment, planning, agent, and handoff anchors.

2. 2

   Review the operating context

   Technical, product, and working-process sources are read as separate domains. Current files take precedence over generic claims, while contradictions and stale descriptions are recorded with their paths and practical effect.

3. 3

   Trace an autonomous delivery path

   Guard asks whether an agent can find scope, discover context, plan, enter the repository, stay inside change boundaries, identify verification, understand review and release expectations, and leave a usable handoff.

4. 4

   Normalize evidence into judgments

   Repository facts support category scores, confidence, limitations, and ordered improvement candidates. A signal affects a score only after its meaning is checked against the repository around it.

5. 5

   Draft the current result independently

   The current report and summary are completed before any earlier audit is read, so an old score cannot anchor a weak current assessment.

6. 6

   Compare one validated prior result when available

   Only a prior result tied to the same repository and a usable revision enters the comparison. Otherwise the current audit remains unchanged and becomes the baseline.

Evidence retains its lineage throughout that path: exact file or repository fact, interpretation, affected category, confidence, and limitation. If one stale product rule weakens context depth, planning, and delivery-path confidence, the report may explain all three effects. It still records one underlying gap and one improvement candidate, not three invented root causes.

How repository signals earn score relevance

Agent frameworks, instruction files, skill directories, task databases, planning scaffolds, and prompt libraries reveal what method appears to be present. Guard still needs evidence that the method is followed and helps an agent deliver stable work.

Fingerprint, adherence, and readiness

Adherence asks whether the repository keeps the method's scope, ordering, acceptance, and verification artifacts current. Readiness asks the broader question: can an agent use the repository's actual evidence to understand, change, verify, and hand off work with low friction? A maintained custom process can be stronger than a stale named framework. Partial adherence is a proportional concern, not an automatic major penalty; it matters most when agents lose scope, order, acceptance criteria, or verification.

Contradictions are equally concrete. Two current instructions that require opposite actions for the same scope can mislead an agent. Different rules for clearly different modes are not a contradiction. Desynchronization is separate: a README may describe a command that the manifest no longer contains, or a product document may no longer connect to active plans. Guard records only material mismatches with a practical effect.

Portability and skill quality receive the same evidence discipline. A tool-specific file is not bad merely because it is tool-specific; the question is whether essential rules also have a durable, generic home. A skill earns credit when its trigger, project paths, constraints, output, verification, and failure handling are usable now. Quantity and fashionable names do not substitute for those properties.

The resulting report follows a plain chain: repository fact → category judgment → weighted score → limitation or completion signal. That chain lets a reader challenge the conclusion. It also prevents a green score from erasing the gaps that still require human prompting.

The nine categories behind the score

Each available category is scored from 0 to 10. Scores of 8–10 are strong, 4–7 are partial, 1–3 are weak, and 0 is absent. When evidence cannot support a judgment, the status is unknown rather than quietly healthy. Every row also carries high, medium, or low confidence. A score of 8 or more requires positive evidence and no unresolved blocker in that category.

The weights reflect the audit's question. Context depth receives the largest share because reliable decisions require more than a runnable command; the delivery path, planning, and verification then test whether that context can reach a checked handoff. The categories are distinct enough to diagnose a gap, but they are not independent facts: one well-evidenced contradiction can legitimately affect several judgments.

1. 1

   Agent delivery path — 15%

   Can an agent move from task intake to a stable, verified handoff? Guard traces scope, context discovery, planning, setup, implementation boundaries, verification, review, release expectations, and recovery. A long instructions file does not compensate for a broken path between those steps.

2. 2

   Context depth — 20%

   Can an agent make decisions from current technical, product, and working-process context instead of guessing? This is the only composite category: those three domains are scored separately, weighted 40/30/30, reduced for material contradiction or desynchronization, then rounded before entering the final formula.

3. 3

   Planning system — 14%

   Can work be scoped against current plans, tasks, acceptance criteria, decisions, and durable artifacts? Guard credits a lightweight custom method when it preserves those properties. It does not award points for adopting a named planning framework or producing documents that no longer guide implementation.

4. 4

   Machine verification — 14%

   Are safe, discoverable checks connected to the code an agent is likely to change? The audit looks for commands, test layers, quality thresholds, smoke checks, and documented completion criteria. It scores the path described by repository evidence; it does not execute that path during this audit.

5. 5

   Cross-agent portability — 10%

   Would essential instructions survive a change of agent or vendor? Tool-agnostic entry guidance, canonical documents, generic check commands, and shared recovery rules help. Critical rules that exist only in one tool-specific file, with no generic fallback, make the operating model fragile.

6. 6

   Skills quality — 9%

   Are agent-facing skills and prompts specific, current, bounded, and verifiable? Guard checks trigger clarity, project adaptation, valid paths and commands, constraints, expected outputs, examples, failure handling, and complexity. A small set of precise skills can score better than a large generic catalog.

7. 7

   Work memory and handoff — 7%

   Can another agent or human recover intent, progress, evidence, decisions, and next steps? Useful traces, decision records, status notes, task artifacts, and explicit recovery rules preserve work beyond one session. Private conversational memory does not provide the same continuity.

8. 8

   Quality gates — 6%

   Do visible review, local verification, and release safeguards reinforce change quality? External CI/CD and branch-protection evidence is credit-only here because another audit owns those controls. When their absence is the only limitation, this category may be null and excluded rather than scored as zero.

9. 9

   Environment safety — 5%

   Are runtime versions, setup, secrets, generated files, test data, and destructive-action boundaries clear enough for safe local work? Guard looks for documented environment expectations and warns on evidence that would make an agent improvise with credentials, production services, or irreversible commands.

How the score is calculated and capped

Guard calculates context depth first because its rounded result becomes one input to the final weighted score. Technical context carries 40%, product context 30%, and working-process context 30%.

weighted_context_score =
    technical_context * 0.40 +
    product_context * 0.30 +
    working_process_context * 0.30

final_context_depth_score = round(
    max(0, weighted_context_score - contradiction_or_desync_penalty)
)

The penalty is 0 when no material contradiction or desynchronization exists, 0.5–1.0 for minor friction, 1.0–1.5 for moderate friction, and 2.0 for a major mismatch that can mislead an agent. A one-point contextual adjustment is permitted only when its direction and evidence are disclosed. It is an exception, not a hidden normalization rule.

Context-depth caps

• Context depth cannot reach 8 unless technical, product, and working-process context are each at least 7 and no major contradiction or desynchronization remains.
• A moderate unresolved mismatch normally caps context depth at 7 unless a current, easy-to-follow source actually resolves it and the report explains how.
• A major unresolved contradiction or desynchronization caps context depth at 6.
• Product context only partially connected to current plans or acceptance criteria normally keeps context depth at 7 or below.

The final weighted formula

weighted_total =
    agent_delivery_path * 0.15 +
    context_depth * 0.20 +
    planning_system * 0.14 +
    machine_verification * 0.14 +
    cross_agent_portability * 0.10 +
    skills_quality * 0.09 +
    work_memory_and_handoff * 0.07 +
    quality_gates * 0.06 +
    environment_safety * 0.05

final_score = round(weighted_total * 10)

quality_gates is the only category that may be null, and only when missing or decorative external CI/CD evidence is the sole limitation. Null does not mean zero. Guard removes that category and renormalizes the remaining 94% of weight:

final_score_without_quality_gates = round(
    (weighted_total_without_quality_gates / 0.94) * 10
)

Labels, calibration, and the documented cap

90-100

Agent-ready

70-89

Mostly ready

40-69

Needs context

0-39

Needs groundwork

Scores of 90 or more are reserved for deep evidence in all three context domains, a clear verification and portable handoff path, and no material unresolved mismatch. Reaching 80 requires an unambiguous current route from task to acceptance, verification, review, and handoff. A moderate unresolved contradiction or desynchronization caps the final score at 79 unless a current source resolves it. A strong repository with one or two meaningful gaps will usually fall in the 70s; a green score may still have high-priority work.

There is no separate hidden floor, final clamp, or tie-breaking rule beyond 0–10 category inputs, the stated formulas, the documented caps, and validation of an integer 0–100 result. The runbook says to round but does not define how an exact half tie is handled, so the article does not invent a convention. The example below avoids one.

A worked example: 72 out of 100

The repository, revision, evidence, and numbers in this example are fictional. For northstar/dispatch-api, technical context scores 8, product context 6, and working-process context 7. One minor desynchronization applies a 0.5 penalty.

weighted_context = (8 * 0.40) + (6 * 0.30) + (7 * 0.30)
context_depth = round(max(0, weighted_context - 0.50))

# weighted_context = 7.10
# context_depth = round(6.60) = 7

The nine category scores are 7, 7, 7, 8, 7, 7, 7, 7, and 8. Their weighted total is 7.19, which becomes 72 — Mostly ready. The dashboard badge is Healthy; that is product tone language, not a second score label. The minor mismatch does not trigger the moderate final cap, and the product-context weakness is already visible in context depth. No contextual adjustment is used.

How to read the result in Guard

The repository card provides orientation. At 72, the score ring and status badge are green and the badge says Healthy. The card border can still be yellow because the checklist contains warning states. This is intentional: the overall score and the worst visible evidence signal answer different questions.

Problems, Watch, Healthy, and Skipped count checklist states, not weighted categories. In the fictional card, four pass, three warn, zero fail, and one skip produce eight total states. The skipped quality-gate signal is a neutral pointer to evidence outside this audit's scope; it does not turn the worked example's scored quality-gates category into null and it does not enter the arithmetic.

Opening the report reveals the exact repository and full commit, what was checked, the direct answer, human-prompting risk, confidence, context judgments, contradictions or desynchronization, delivery path, method adherence, portability, skills, all nine category rows, calculation, evidence, limitations, and ordered improvement steps. The compact card and the report do not use different scores. They expose different levels of the same current-revision result.

In the detail view, completed entries sit under Reports; the newest is marked Current, and the report offers the exact actions Copy and Download. Those controls preserve the reviewable report rather than replacing it with a dashboard-only summary.

History is comparison evidence, not a forecast. A prior point appears only when Guard can validate and read a usable earlier result for the same repository. The UI may mark an old card Out of date after seven days, but that is a freshness cue rather than automatic score decay. The score still describes its audited revision.

The card action is Rerun. Inside its scheduling dialog, the one-off action is Re-run now; the detail page uses Rerun audit. A rerun can be unavailable when the selected revision has not changed, so the presence of this static illustration is not a promise that every live control is always enabled.

Where the audit ends and improvement begins

The audit may recommend ordered improvements in documentation, skills, verification, planning, product context, process, or another clearly bounded area. Each candidate needs an identifier, a title, repository evidence, a reason, a bounded scope, a priority, and a completion signal that a reviewer can verify.

• Critical means the gap blocks safe delivery.
• High means fixing it should noticeably reduce repeated prompting.
• Medium means useful tightening.
• Low means polish or hardening.

Those recommendations describe evidence at the audited commit. They are not current repository truth after later changes, and they are not permission to write. A person must decide whether the proposed completion signal reflects the intended product and process. Before any later edit, the repository and the gap must be checked again against the current revision and change boundary.

There is currently no AI-readiness Autofix action in the product. Guard therefore does not show an improvement panel, issue, pull request, or automatic agent-documentation repair on this page. The current boundary is a reviewable, human-gated recommendation in the audit report. Presenting more would turn a future contract into a current capability.

What changes on a rerun—and what does not

A defensible result keeps its limits visible:

• Static evidence can show that a verification path is discoverable, but not that builds, tests, scanners, services, or deployments succeed.
• Repository documents can describe product intent and process, but Guard cannot resolve missing ownership or acceptance decisions by inventing prose.
• A named framework or a large skill collection does not prove adherence, currency, portability, or project fit.
• Provider metadata, deep history, external gate state, or earlier results may be unavailable. The report lowers confidence or states the limitation instead of filling the gap with an assumption.
• The result applies to one full commit. A new plan, command, product rule, environment boundary, or handoff convention can change readiness without a large code diff.

Every current audit is scored independently. If no usable earlier result exists, the current score stands on its own and establishes the baseline; Guard omits the previous value and relation section. When a prior result is usable, the comparison names the exact revisions and distinguishes unchanged, new, and resolved gaps. Movement can come from a substantive repository change, corrected evidence, a material scope or guidance change, or a scoring-method change. Cosmetic rewriting is not evidence of improvement.

Optional repository guidance is reread at the current revision. Evidence-consistent changes may affect the result; unchanged guidance cannot explain a score delta. In either case, guidance cannot suppress findings, expand permissions, or override the audit's safety and evidence rules.

Keeping the operating context current

A rerun can rise, stay flat, or fall as product context, verification, planning, and handoff paths evolve. The intended outcome is a repository whose operating context remains current enough for agents to add features without layering new work over avoidable ambiguity.

Recurring audits make drift visible. Human-reviewed improvements can address the smallest well-evidenced gaps, and a later audit evaluates the new revision from scratch. That cycle keeps a healthier foundation for ongoing agent-led development without promising autonomous correctness.