Architecture Audit — act101 Agent Skill

Architecture Audit

Depth: Level 3 (Full Audit).

See ../analysis-protocol/references/protocol.md for: artifact directory structure, the investigation loop, depth levels, summary format, token budget rules, and project map structure. Read that document before proceeding.

Phase 0: Load the Prior Project Map (before any tool dispatch)

Before dispatching anything, check for an existing project-map.md at the workspace root. If it exists, read it first and extract:

• Refuted & Re-characterized Findings ledger — these are hypotheses already investigated and disproven. Do not re-investigate them from scratch in Phase 2. Re-open a refuted finding only if Phase 1 surfaces new structural evidence that contradicts the prior refutation; otherwise carry each entry forward verbatim and note "previously refuted (date), no new evidence" in the report. This is the single most important reason to read the map first — it stops every audit from re-flagging the same disproven smells.
• Analysis History table — for the trend verdict (improving / stable / degrading) and to append (not overwrite) the new row.
• Chokepoints, hotspots, cycles, pattern counts — capture prior numbers so the new report can show deltas (e.g. "god_function 1,321 → 1,651"), and so a newly appeared cycle or chokepoint is flagged as a regression.
• Scan-score trend: if .act/scan-history.jsonl exists, run act trends --root <repo> for the score series, per-class count deltas, and banded verdict — never hand-diff scan scores across runs. Analyzer outputs not in the history records (chokepoints, clusters, hotspot rankings) still come from the prior map's numbers as above.

Also read remediation-log.md (workspace root, if present). This is the append-only ledger the architectural-refactoring skill writes — one row per remediation, keyed to a finding ID. It is the other half of the audit → refactor → re-audit loop: it tells you which prior findings were claimed fixed since the last audit, and how. Treat each RESOLVED/PARTIAL row not as truth but as a hypothesis to re-verify in Phase 2 against this run's fresh structural evidence:

• If the structure confirms the fix (the cycle is gone, instability dropped, the god-object split), reflect it in synthesis — mark the recommendation resolved, move the item out of Weaknesses, and show it in the delta/trend.
• If the structure contradicts the claim (the row says RESOLVED but the cycle is still present, or a "split" reintroduced coupling elsewhere), that is a regression / incomplete-remediation finding — surface it explicitly with the conflicting evidence.

The audit only reads this log; the refactoring skill owns the writes. Never edit remediation-log.md from the audit.

If no project-map.md exists, this is the first audit — note that, proceed to Phase 1, and create the map (including an empty Refuted ledger) during synthesis. A remediation-log.md with no prior map is an inconsistency — note it and treat its rows as unverified claims.

Phase 1: Parallel Tool Dispatch

Dispatch all available tools in a single parallel batch — never sequentially. Each subagent runs one tool, saves raw JSON to raw/<tool-name>.json, returns a structured summary.

Must-have tools (report is not useful without at least some of these):

Interpret analyze_seams through the cluster output that feeds it. total_seams: 0 only means there are no crossing edges between the detected clusters. If analyze_clusters reports fewer than two clusters, hub_collapse: true, or one cluster containing the whole scope, do not report "no boundary"; report the cluster artifact and investigate with dampen_top_k, split_module, analyze_surface, or simulate.

Extended tools (use if available, skip and note in manifest if not):

Conformance worked example (real run): a repo declaring

[architecture]
[[architecture.deny]]
from = "src/core/**"
to = "src/ui/**"
reason = "core must not depend on presentation"

where src/core/logic.ts imports src/ui/render.ts returns contract_present: true and one violation: kind: "deny", rule: "src/core/** -> src/ui/**", file: "src/core/logic.ts", line: 1, evidence src/core/logic.ts --imports--> src/ui/render.ts, with the rule's written reason echoed. Report violations with that file:line — it is the offending import statement, not the rule definition.

Phase 2: Smell Taxonomy + Hypothesis Formation

Before dispatching any investigation subagents, form explicit hypotheses using this taxonomy. One module appearing in multiple columns is a stronger signal.

Anomaly flags — investigate regardless of smell match: - Cluster containing 1 file (orphan or misclassified) - Cluster containing >30% of all files (god cluster) — analyze_clusters now self-discloses via hub_collapse=true + top_hubs (named hub files); consume these fields from the result and report the named hubs; the >30% rule remains as a cross-check (it also catches large clusters whose cohesion sits above the 0.05 disclosure floor) - All instability scores near 0 or near 1 (degenerate dependency structure) - Seam with 0 API symbols (disconnected component) - Dead code in a file that is also in a cycle (phantom dependency) - Zero cycles in a codebase >100 files (suspiciously clean)

Phase 3: Full Audit Synthesis

After all investigation subagents return:

1. Cross-reference findings across all categories — a module appearing in hotspots, coupling, AND cycles is a compounding risk
2. Build evidence chains — not "instability = 0.94" but "module X has instability 0.94, is in 2 cycles, and its API surface exposes 23 symbols across a seam to cluster B — skeleton shows it handles both auth and request routing, confirming god-object smell"
3. Note negative space — absence of expected problems is a meaningful finding
4. Record every refuted or re-characterized hypothesis — for each Phase 2 hypothesis that came back refuted, partially refuted, or re-characterized (the real issue differs from the hypothesized smell), and for each tool output that is an artifact rather than a finding (e.g. degenerate dead-code/cohesion/layers results), capture it with its disproving evidence. These feed the project map's Refuted & Re-characterized Findings ledger.
5. Reconcile claimed remediations — for each remediation-log.md row read in Phase 0, state the verdict from this run's evidence: confirmed (fold into the map, mark the recommendation resolved, show the delta), or contradicted (surface as a regression / incomplete-remediation finding). Do not silently drop a claimed fix that the structure no longer supports.
6. Write report.md, then update project-map.md (full rewrite of all sections, carrying the Refuted ledger forward and reflecting confirmed remediations — see Project Map Updates)

Report Structure

# Architecture Audit: <project name>

## Overview
Files, symbols, languages, analysis date.

## Executive Summary
2-3 sentence assessment. Explicit verdict: **Ready** / **Needs work** / **Not ready**.
One-sentence justification for the verdict.

## Module Map
Clusters with sizes, labels, cohesion scores. Anomalies noted.
Module roles (entry point, routing, business logic, data access, utility, etc.).

## Entry Points
Application entry points by kind (application, HTTP route, CLI, event listener, test,
public API).

## Layer Architecture
Detected layers with directory mappings. Violations with evidence.

## Dependency Structure
Instability rankings with interpretation — what the scores mean structurally.
Stability violations.

## Circular Dependencies
All cycles: length, members, confirmed break points from investigation.

## Boundary Assessment
Seams: API surface width, confirmed leaky vs. clean.

## Complexity Hotspots
Ranked hotspots with skeleton context from investigation.

## Chokepoints
High-centrality files with blast radius and split recommendations.

## Dead Code
Confirmed unreachable symbols. Zombie code noted separately.

## Code Patterns
Findings grouped by pattern type and severity.

## Strengths
What the architecture does well. Notable absence of expected problems.

## Weaknesses
Confirmed structural issues with evidence chains.

## Refuted & Re-characterized Findings
Hypotheses investigated and NOT confirmed (refuted / partially refuted / re-characterized),
and tool outputs that are artifacts rather than findings. Each with its disproving evidence.
Include findings carried forward from the prior project map (mark "previously refuted, no new
evidence"). This section prevents future audits from re-flagging disproven smells.

## Risks
Causal chains: what breaks first, what cascades, minimum intervention.

## Recommendations
Prioritized, actionable steps, each linked to a confirmed finding.

When the audit confirms structural findings that warrant remediation (cycles, god
objects, coupling hotspots, dead code), the single recommended next action is to run the
`architectural-refactoring` skill — **not** a cherry-picked inline fix. That skill executes
the prioritized set as a unit and records each remediation to `remediation-log.md`, which is
what closes the audit → refactor → re-audit cycle and lets it go deeper each pass. Proposing a
one-off "move X, fix two imports, re-run" edit here short-circuits the cycle and leaves no
durable remediation record. The specific act MCP tool calls are the *mechanism* the refactoring
skill uses, not a substitute for invoking it.

Because the handoff is artifact-based (this report + `project-map.md` + `remediation-log.md` on
disk), the refactoring skill needs no conversation context. Phrase the next action so it works
from a clean slate, e.g.: "Clear context, then run `/architectural-refactoring` — it rehydrates
from this report and the project map." Use individual tool-call recommendations only for findings
that are genuinely outside a refactoring pass (e.g. "add a coverage run before the next audit").

Project Map Updates

Updates all sections of project-map.md (workspace root, full rewrite). Appends to the Analysis History table.

Confirmed remediations: when this run's evidence confirms a remediation-log.md claim, reflect it in the rewritten map — drop or down-rank the resolved item in Chokepoints & Risks / Weaknesses, and let the resolution show in the delta and trend verdict. Do not copy the remediation log into the map and do not edit the log itself — the map records current state, the log records actions taken, and the refactoring skill owns the log. A claim the structure contradicts stays an open finding (and may warrant a Refuted-ledger entry if the "fix" was based on a misdiagnosis).

Refuted & Re-characterized Findings ledger (required): the project map carries a persistent ## Refuted & Re-characterized Findings section (see the protocol's Project Map Structure). On every run:

1. Carry forward every entry from the prior map's ledger — never drop a refutation just because this run didn't re-test it. Keep its original "Since" date.
2. Add each newly refuted / re-characterized hypothesis and each newly identified tool artifact from this run's Phase 2, with the disproving evidence and this run's date.
3. Update an entry's status only if this run found new evidence that overturns the prior refutation (e.g. a once-clean boundary now genuinely leaks) — note the change explicitly.

Each ledger row: | Finding | Status (REFUTED / RE-CHARACTERIZED / ARTIFACT / UNRELIABLE) | Since (date first established) | Evidence / why |. This ledger is what Phase 0 reads on the next run to avoid re-investigating disproven smells.

Rules

1. Dispatch Phase 1 in a single parallel batch — never sequentially
2. Write all hypotheses before dispatching Phase 2 — no browsing without a hypothesis
3. Evidence chains, not data points — explain what scores mean structurally
4. Follow new signals — if a Phase 2 subagent finds something unexpected, dispatch a follow-up (capped at one extra round)
5. Note negative space — absence of expected problems is a finding
6. Executive summary must include an explicit Ready / Needs work / Not ready verdict

Worked Example: Clone-Mass Dispatch

Call (default min_tokens; scoped to source):

analyze_clones(include=["crates"])

Top of result (act repo, 2026-06-12, min_tokens 50):

{
  "clone_classes": [
    {
      "id": "clone-3407fede907f0634",
      "clone_type": "type-2",
      "token_count": 57,
      "members": [
        { "file": "crates/act-refactor/src/operations/actionscript/operations/add_documentation_comment.rs",
          "start_line": 24, "end_line": 30 }
        // … 1506 more members
      ],
      "remediation": {
        "operation": "extract_function",
        "note": "All members are function definitions or lie within function bodies."
      }
    }
  ],
  "summary": {
    "files_analyzed": 5392,
    "files_with_clones": 3970,
    "clone_class_count": 8156,
    "duplicated_tokens": 5067066,
    "min_tokens": 50,
    "test_files_excluded": 47488
  }
}

Reading this: the top class by mass (57 tokens × 1507 members = 85,842 mass) has a remediation.operation: "extract_function" pointer — every member lies in a function body, so extract_function at the first member site is the right next step. The 5,067,066 duplicated_tokens total against 5,392 files analyzed signals systematic abstraction debt, not isolated copy-paste.

Optional Enrichment: Runtime & Git Evidence

The structural audit above is AST/graph-based. When the workspace has a coverage run and git history, enrich each structural finding with evidence overlays so the report reflects what actually runs and what actually changes — not just the static graph. This is optional: skip any overlay whose evidence is absent and say so.

Tier: the four overlays (coverage_overlay, churn_hotspots in workspace mode, co_change_clusters, ownership_map) are Architecture and enforce that tier themselves; the base structural audit is unaffected. If an overlay is tier-blocked, its dimension is UNASSESSED — state it, never imply "clean."

Enrichment workflow (after the structural audit):

1. coverage_overlay with the lcov report — a complexity hotspot or chokepoint with covered: false is a high-risk node (complex, central, untested).
2. churn_hotspots (workspace mode) — a high-coupling / high-instability module that is also high-churn is an active design-debt accumulation point.
3. co_change_clusters — where these disagree with the static analyze_clusters boundaries, you have hidden coupling the structure does not show.
4. ownership_map — a low bus factor on a chokepoint or god-module is a compounding people-risk on top of the structural risk.

When enrichment runs, every Risk and Recommendation should cite the structural finding AND its overlay evidence — e.g. "module X: instability 0.94, in 2 cycles (structure) + uncovered + 31 commits in 90 days + bus factor 1 (overlays) → top-priority refactor." Overlays are window-bounded: report unmapped/modeled_kinds and the coverage/git window as caveats. Absence of overlay evidence is "no evidence," not absolution.