Check consistency — answer each question:
A. Implementation coverage in docs
Apply the same routing table as start step 2 to each changed impl/schema file:
cmd/bausteinsicht/*.go → spec/02 and spec/01internal/model/types.go / schemas/ / internal/schema/ → spec/03internal/sync/*.go → spec/05- New
internal/<pkg>/ directory → arc42/05, arc42/06, and architecture.jsonc
- New runtime data flow in existing package →
arc42/06
- New cross-cutting pattern →
arc42/08
- Any other
internal/<pkg>/ with user-visible change → spec/01, spec/02
- Significant design tradeoff → new ADR in
src/docs/arc42/ADRs/
Always run this concrete check (not just judgment) when any internal/ or cmd/ directory was added, renamed, or removed in the diff:
make arc42-drift-check
Non-zero exit → ❌ blocking (a real package has no container element in architecture.jsonc, or vice versa). This is a scripted version of the routing-table rule above — it exists because that rule was manual-judgment-only for a long time and 11 packages drifted out of the model undetected (#524).
Also run this when a new cmd/bausteinsicht/*.go command or subcommand was added:
make arc42-process-coverage-check
make arc42-runtime-coverage-check
Non-zero exit → ⚠️ non-blocking (advisory only — a textual mention check, not a semantic one; see the script headers). Flags commands not yet mentioned in §3.1.1's process diagram (chapters/03_context_and_scope.adoc) or chapter 6's runtime scenarios (chapters/06_runtime_view.adoc). This exists because §3.1.1 and chapter 6 both drifted badly behind the CLI's real command set before being caught (#535).
Also run this when a new *-components view is added to architecture.jsonc:
make arc42-level2-coverage-check
Non-zero exit → ❌ blocking (a structural check, like arc42-drift-check — not a text heuristic). Flags a view with no matching "Level 2" section in chapter 5. This exists because 4 of 10 views (importer-components/exporter-components/search-components/diagram-components) went undocumented for a long time — deliberately deferred in #526, then closed in #539.
B. Doc coverage in tests
For each new acceptance criterion or spec section added: is there a test covering it?
grep -rn "<feature-name>" --include="*_test.go" .
C. E2E test coverage — every user-visible new feature or cross-command bug fix needs an
end-to-end scenario, not just a unit test. Unit tests catch a wrong return value; they do not
catch "command A writes a value command B then rejects" — that class of bug only shows up when
the pipeline runs for real. (See Issue #512:
import --from structurizr wrote a layout value that sync's own validation rejected — shipped
in v1.2.0 with zero test coverage anywhere in the repo, unit or e2e, because no test ever ran
import output through sync.)
For each changed/added file, check whether it falls into one of these triggers:
- New
cmd/bausteinsicht/*.go command or subcommand
- New or changed
--flag with user-visible effect
- A fix or feature where the input of one command is produced by another (import→sync,
sync→export, snapshot→restore, etc.) — i.e. anything that only breaks when chained
- A bug fix whose root cause is "component X assumes something about component Y's output/format"
If any trigger matches, search for a scenario that actually chains the relevant commands:
grep -rln "<command-name>\|<scenario-keyword>" e2e/*_test.go
A unit test on the producing side alone (e.g. only testing the importer's output struct) does
not satisfy this — the check must confirm the consuming command (sync/export/etc.) actually
runs against that output in the test, the same way a real user's shell pipeline would.
- Trigger matched, no e2e scenario chaining producer→consumer → ❌ (blocking)
- Trigger matched, existing e2e test covers it but doesn't assert on the specific new behavior → ⚠️
- Pure internal refactor with no user-visible or cross-command effect → no check needed
D. No stale docs — check for renamed/deleted exported symbols still referenced in docs.
Two-pass extraction (handles both top-level funcs and methods):
git diff main...HEAD -- '*.go' ':!*_test.go' \
| grep '^-' \
| grep -E '^-\s*(func|type|const)\s+[A-Z]' \
| grep -oE '\b[A-Z][A-Za-z0-9_]+' | sort -u
git diff main...HEAD -- '*.go' ':!*_test.go' \
| grep '^-' \
| grep -E '^-\s*func\s+\(' \
| grep -oE '\)\s+[A-Z][A-Za-z0-9_]+' \
| grep -oE '[A-Z][A-Za-z0-9_]+' | sort -u
Then for each extracted symbol: grep -rn "<Symbol>" src/docs/
- Stale reference to a removed/renamed symbol in docs → always ❌
- Changed-but-undocumented symbol → ⚠️, except: CLI flag, command name, public schema field → ❌
