/arch-check

name: arch-check
description: Use to check a feature's code against the charter's architecture rules — dependency layering, cycles, forbidden patterns, file naming, file size. Triggers — "/engineer.arch-check", "architecture check", "check architecture fitness", "does this follow the charter", "check layering".

arch-check

Run the charter architecture fitness check — Checkpoint 7 (Light Verify), alongside `crap-analyzer`. Turns the charter's architectural vision from prose into an objective gate: `dae_arch.py` reads the manifest's `architecture:` rules and reports violations.

Read-only on the codebase — it reports, it does not fix.

When to use

Checkpoint 7, after the feature's code is implemented and refined. Also useful as a standalone audit (`--full`) of an existing project.

**Not for:** change-risk analysis (`crap-analyzer`); artifact consistency (`consistency-check`); fixing violations (that is a human/agent decision per violation).

Workflow

Step 0 — Entry gate

Verify the prior checkpoint is complete: run `${CLAUDE_PLUGIN_ROOT}/scripts/dae_handoff.py <feature-dir> --through 6`. On a non-zero exit, **stop** and surface the gap to the human.

Verify branch hygiene: run `${CLAUDE_PLUGIN_ROOT}/scripts/dae_branch.py <feature-dir>`. On a non-zero exit, **stop** and surface the message to the human — switch branches and re-invoke. The check honors the `git.manual: true` manifest opt-out.

After the gate passes, show the **pipeline breadcrumb**: run `${CLAUDE_PLUGIN_ROOT}/scripts/dae_progress.py <feature-dir>` and present its output to the human — it shows where this checkpoint sits in the DAE pipeline. The breadcrumb is advisory: a non-zero exit or a missing `progress.md` never blocks the skill. Then create one TodoWrite todo per workflow step below. See `${CLAUDE_PLUGIN_ROOT}/references/progress-indicator.md`.

Step 1 — Run the check

Run `${CLAUDE_PLUGIN_ROOT}/scripts/dae_arch.py <methodology-root>` (add `--full` for a whole-project audit). If it reports "no `architecture:` section", tell the user the charter has no machine-readable architecture rules yet and stop.

Step 1.5 — CRAP analysis

CP7 Light Verify is arch-check **plus** `crap-analyzer`. If crap-analyzer hasn't run on the current diff, run it now over the feature's changed code. Keep its summary for the handoff: max CRAP, the offenders over `quality_thresholds.crap_max`, and the command. It is external and writes no handoff of its own, so this is where CP8's refinement-advisor reads it.

Step 1.6 — Real-app run

Read `manifest.verify_app`. Unless it is `none`, invoke that project skill (`.claude/skills/<verify_app>/SKILL.md`) for this feature's feature-map rows: Launch → Doctor → Drive → Evidence → Cleanup, writing evidence to `features/<slug>/evidence/`. No row for this feature → add it first (see `${CLAUDE_PLUGIN_ROOT}/references/verify-app-skill.md`). A failing run is a verification failure, not a skip. For features created on or after the cutoff, `dae_handoff.py` refuses a CP7 handoff that has no `real_run` block with existing evidence files. Passing tests don't count. Older features pass with a warning.

Step 2 — Present violations

Group the violations by kind (layering first — it is the architectural-vision core). For each, show `file:line` and the rule. Do not auto-fix.

Step 3 — Triage with the human

For each violation, the human decides: a real break (fix the code), or a rule that no longer fits (amend `manifest.architecture` — and the charter prose). `dae_arch.py` exiting non-zero means Checkpoint 7's architecture-fitness exit criterion is unmet until the violations are resolved.

Step 3.5 — Runbook gate (if runbook.md exists)

If `features/<slug>/runbook.md` exists, check that every step blocking a deploy-related AC is `completed: true`. If any blocking step is open while its dependent AC is asserting `met: true`, surface it as a verification gap and refuse to mark CP7 complete. The runbook's `blocking_acs` list is the source of truth — see `engineer/skills/plan/references/runbook-template.md`.

Step 4 — Handoff

Emit a summary per `${CLAUDE_PLUGIN_ROOT}/references/handoff-summary.md`. `checkpoint: 7`; the `exit_criteria` block asserts the architecture-fitness criterion with `verified_by: tool` and the `dae_arch.py` exit status as evidence, and carries crap-analyzer's summary as a `crap_results` block (`max_crap`, `offenders: [{symbol, file, crap, coverage}]`, `command`). CP8's harden and refinement-advisor read that block. On an onboarded project it also carries the `real_run` block (`skill`, `evidence` paths) and a "feature works in the real app" criterion, `verified_by: tool`, quoting the observed result. `recommended_next`: "/engineer.harden (CP8)".

References

• [Foundation Design](https://www.notion.so/3585ecdee0e2811bbc67ff4913c03207) —

the `architecture:` manifest section (§2); the Checkpoint Exit Contract (§8)