---
{"description":"Gather deterministic architecture-fitness evidence with archfit: full checks, scorecards, deltas, SARIF/JSON findings, tool coverage, and agent_tasks. Use when a repo has .archfit.yaml or the user wants architect to combine its review with archfit. Produces hard facts for architecture-review to calibrate, not a replacement for independent design judgment. NOT for running archfit LLM review as source-of-truth, changing archfit config, baselining findings, or applying fixes.","name":"tools-archfit"}
---

# archfit deterministic evidence

Use archfit as a deterministic measurement and gate engine. It supplies whole-repo
facts; the architect still judges intent, domain volatility, runtime/deploy
context, false positives, and missing risks.

## When to use

Use when a target repo contains `.archfit.yaml` or `archfit.yaml`, when `archfit`
is available on `PATH`, or when the user asks to combine architect review with
archfit output. Use it during `architecture-review` before final triage/scoring
so hard facts can reduce sampling bias.

Do not use this skill for:

- `archfit analyze --ai-summary` or `archfit explain <fingerprint>
--ai-summary` AI narration as primary evidence;
- `archfit config init`, `config update --apply`, `baseline`, `config enrich`
  (labels/owner/volatility/subdomain), `config init --ai-classify`,
  `config enrich ... --apply`, or config writes unless the user explicitly asks
  for config work;
- applying fixes from `agent_tasks`;
- replacing the architect's independent evidence gathering and Balanced Coupling
  judgment.

## Skill navigation

- Missing or absent config: return to `architecture-review`; record archfit as
  missing or skipped. Optional archfit absence is a coverage gap, not a blocker.
- Current skill: run deterministic archfit commands, summarize facts, and build
  a calibration matrix.
- Next skill: return to `architecture-review` for independent verification,
  scoring, and report writing; use `methodology-architecture-fitness` for checks
  that should become enforced gates.

## Read-only discipline

Prefer existing config only. Write command outputs to a temp directory outside the
target repo. Do not create baselines, labels, generated reports, or config patches
inside the repo without explicit user approval.

If archfit or a child tool writes caches or indexes under the target repo, record
that path as generated tool state. If the output path is inside the scanned root,
warn that reports can contaminate measurements and move future outputs outside
the repo or exclude them.

## Deterministic command set

Use the local binary if present; otherwise use `archfit` from `PATH`.

```sh
ARCHFIT=archfit
if [ -x ./archfit ]; then ARCHFIT=./archfit; fi
if [ -x ./.bin/archfit ]; then ARCHFIT=./.bin/archfit; fi
```

Run only commands that fit the repo and time budget. `analyze` is report-only:
it exits `0` when analysis completes even when findings exist; read `verdict` and
`findings` from its output. `check` enforces configured gates: `0` pass, `1`
violation, `2` warning or strict-tool failure, and `3` config/runtime error.
Treat `check` exits `1` and `2` as evidence, not command failures. Invalid JSON or
exit `3` from either command is a tool failure.

```sh
# Tool/config health.
$ARCHFIT doctor

# Full deterministic facts as JSON: findings, metrics, classified_edges,
# agent_tasks, and the coupling_balance score.
$ARCHFIT analyze --config .archfit.yaml --json

# Same report rendered as the coupling_balance scorecard.
$ARCHFIT analyze --config .archfit.yaml --format scorecard

# Human-readable deterministic audit (text is the default format).
$ARCHFIT analyze --config .archfit.yaml

# Report-only delta facts, only when a meaningful base ref is known.
$ARCHFIT analyze --config .archfit.yaml --base <base-ref> --json

# Enforce current configured gates.
$ARCHFIT check --config .archfit.yaml --json

# Enforce only the delta against a meaningful base ref.
$ARCHFIT check --config .archfit.yaml --base <base-ref> --json

# Optional CI annotation artifact (SARIF to stdout).
$ARCHFIT check --config .archfit.yaml --sarif
```

Plain `archfit explain <fingerprint>` is deterministic finding detail and may be
used as evidence. Do not run `archfit analyze --ai-summary` or `archfit explain
<fingerprint> --ai-summary` unless the user specifically wants Archfit's AI
narrative. If you do, label it `advisory_ai`, capture parse/runtime failures, and
never cite it as deterministic evidence.

## Extract these facts

From the JSON, scorecard, or text output, extract and summarize:

- `tool_coverage` and `coverage_gaps`: missing, failed, skipped, and stale tools;
  confidence impact.
- `summary`, the single `coupling_balance` dimension (`score.overall`/
  `overall_band`, confidence, evidence refs), and per-metric results in
  `metrics[]`. archfit synthesizes only `coupling_balance`; derive the other six
  architect dimensions from findings, metrics, and your own evidence.
- `findings`: IDs, severity, status (`new`, `baseline`, `fixed`, `waived`,
  `expired_waiver`), `rule_id`, files, modules, and `kind` (`gate` or
  `advisory`).
- `agent_tasks`: machine-readable repair tasks (`finding_id`, `rule_id`, `goal`,
  `constraints`, `files`, `validation`); emitted for active gate findings only.
- dependency metrics: `cycle` and `blast_radius` where present in `metrics[]`.
  archfit emits no hub or instability metric — get those from codegraph.
- coupling facts: archfit scores each classified cross-boundary edge with the
  book equation (`balance = max(|strength - distance|, 10 - volatility) + 1`,
  1–10, scorer `bc_score.v3`). Each `bc/imbalanced_coupling` finding carries its
  BC fields in `matched_by`: `score_value`, `score_band`, `cheapest_move`,
  `distance_basis`, `strength`, `distance`, `volatility`. The `classified_edges`
  summary holds `mean_balance`, `scored`, `abstained`,
  `by_strength`/`by_distance`/`by_volatility`, and `llm_approved`. Strength includes
  `symmetric` (clone-derived, ordinal 9); volatility may be `undeclared`/`unknown`
  (scored worst-case); abstained edges (unknown strength or distance) are excluded
  from `mean_balance`.
- config quality signals from `config_warnings` and module declarations:
  generated or under-specified modules, missing owner, deploy unit, subdomain,
  volatility, public/private boundary, or weak warn-only rules.
- delta facts: new, existing/baseline, resolved, severity-changed, and
  touched-by-delta findings where available.
- artifact/cache noise: `.archfit-cache`, `.codegraph`, `.gitnexus`, generated
  reports, package caches, vendored external caches, or output under the target
  root.

Absence of findings is evidence only when the relevant tool coverage is present
and current. A green score on missing/thin evidence is a calibration concern, not
proof of architectural health.

## Architect calibration matrix

Return this matrix to `architecture-review` whenever archfit output was used:

```yaml
archfit_calibration:
  source_commands: []
  artifacts: []
  confirmed: []
  severity_adjusted: []
  false_positive_or_noise: []
  missed_by_archfit: []
  config_changes: []
  new_fitness_checks: []
  labels_to_confirm: []
  confidence_impact: none # none | low | medium | high
```

Classify with independent evidence:

- `confirmed`: architect verified the same issue in code, graph, runtime, deploy,
  or CI evidence.
- `severity_adjusted`: archfit fact is real, but composition-root role,
  ownership/deploy distance, lazy-import policy, generated code, or low domain
  volatility changes severity.
- `false_positive_or_noise`: cache/generated artifact, output contamination,
  tool limitation, or configured role makes the finding not architecture risk.
- `missed_by_archfit`: meaning-level risk not in deterministic facts, such as
  functional coupling without import edges, duplicated business rules, prompt/tool
  contract drift, deploy selector drift, slow/flaky architecture-adjacent tests,
  or supply-chain/runtime topology risk.
- `config_changes`: `.archfit.yaml` improvements that would make deterministic
  facts more honest, especially module ownership, deploy units, public/private
  boundaries, subdomain, volatility, and stronger gates.
- `new_fitness_checks`: executable checks to add after design/repair.
- `labels_to_confirm`: architect-inferred subdomain/volatility/strength labels a
  human should approve before deterministic gating uses them. Strength labels
  live in `.archfit-labels.yaml` (`from`/`to`/`strength`/`status`/`provenance`/
  `confidence`, plus `rationale`/`evidence_hash`); only `status: approved`
  entries override the SCIP hint, and the labelable strengths are
  contract/model/functional/symmetric/intrusive. Flag heavy `provenance: llm`
  labeling — archfit drops `coupling_balance` confidence a band when ≥20% of
  scored edges rest on non-high-confidence LLM labels.

## Balanced Coupling handling

archfit now scores edges with the book's own equation (scorer `bc_score.v3`,
ordinals matching the book: contract 1, model 3, functional 8, symmetric 9,
intrusive 10), so its `coupling_balance` is book-aligned in math. It still cannot
own the business truth behind the inputs. For every important coupling claim,
apply `methodology-balanced-coupling` and confirm what archfit could only declare
or infer:

- strength: archfit's SCIP-based strength tops out at `functional` (contract and
  intrusive are deterministic; model-vs-functional is heuristic; `symmetric`
  comes only from clone detection). Confirm the model/functional/contract
  distinction by reading the crossing types; promote it with an approved
  `.archfit-labels.yaml` entry, not a prose guess.
- distance: archfit reports a `distance_basis` (code_structure / ownership /
  deploy_unit). `runtime_async` is report-only and never moves distance — fold
  runtime/deploy distance in yourself.
- volatility: archfit derives it from config `volatility:`/`subdomain:` and an
  inferred-volatility cascade — never from churn or path/name guessing, and it
  cannot see provider-switch (implementation) volatility in generic/supporting
  code. Confirm declarations against the business domain; `undeclared`/`unknown`
  volatility scores worst-case and is a config gap to flag, not a finding.
- balancing move: archfit suggests a `cheapest_move` (reduce_strength /
  reduce_distance / lower_volatility / declare_volatility); treat it as a
  hypothesis and confirm it against the relationship record.

Do not pass through archfit's `coupling_balance` score as the architect score.
Use the per-edge `score_value`/`score_band` and the `classified_edges`
distribution as evidence, then score from relationship records and coverage.

Apply coverage-gap calibration consistently so the magnitude is reproducible,
not just the direction:

- When edge classification is absent (`scip absent` / "no classified
  cross-boundary edges"), set `coupling_balance` confidence `low` and cap the
  band at `mixed` (≤ 60, default ~50) unless you classify the edges yourself with
  codegraph, `go list`, or dependency-cruiser.
- When `classified_edges.scored` is a low fraction of `total` (many `abstained`
  unknown-strength/distance edges), `mean_balance` rests on thin coverage — treat
  it like absent classification: low confidence, cap at `mixed`.
- When GitNexus covered only part of the changed files, apply the same cap to
  `change_locality`.
- A clean `coupling_balance` dimension with `confidence: medium` and an `n/a`
  metric is a coverage gap, not a strong result.

## Output

Return a concise evidence summary:

- commands run and artifacts produced;
- exit statuses interpreted as findings/warnings/failures;
- tool coverage and confidence impact;
- top deterministic findings and agent tasks by severity/risk;
- scorecard/delta highlights;
- calibration matrix;
- smallest follow-up checks needed to verify hypotheses.

## Hard rules

- Deterministic archfit facts can seed review; they do not replace independent
  verification or user/domain context.
- No high-quality architecture claim from missing or unclassified evidence.
- No source or config writes without explicit approval.
- No treating `archfit analyze --ai-summary` / `archfit explain <fingerprint>
--ai-summary` narration as source-of-truth; plain `explain` remains
  deterministic finding detail.
- No counting an archfit pass as proof of correctness, security, performance, or
  all architecture quality; it only says configured checks and measured metrics
  passed under the observed coverage.