feat: add architecture semantic coverage checks

archify/SKILL.md

@@ -85,6 +85,7 @@ Read Mermaid for topology and meaning, then author fresh Archify JSON; do not me
 - For sequence diagrams, omit `meta.column_fit` for the stable `fixed` layout. Set it to `"spread"` when a wide viewBox would otherwise leave unused horizontal space or when meaningful participant labels do not fit the fixed boxes; do not shorten semantic labels before trying `spread`.
 - Component types are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`; variants are `default`, `emphasis`, `security`, and `dashed`.
 - Relationship labels are semantic data. When one collides, move the label, adjust the route or spacing, then shorten the wording while preserving meaning. Omit only wording that is already fully implied by both endpoints and contains no protocol, action, direction, synchronous/asynchronous behavior, or cross-boundary mechanism. Preserve every meaningful label; deleting it is not a geometry repair. If a relationship starts unlabeled because its endpoints fully imply it, explain why the wording is redundant; this is a semantic authoring choice, not a geometry repair.
+- For repository-backed Architecture, author `semanticChecks` from verified evidence before layout. The renderer also checks the pinned repository tree for scheduler, cron, worker, and background runtime source paths. Include every material entrypoint or controller family, lifecycle scheduler/background worker, and direct external-system management path as `requiredComponents`, `requiredEdges`, or `requiredPaths`; set `requireExternalLabels` when external operations must be named. Resolve every coverage warning by adding the fact or recording a specific, reasoned `omissions` entry. Use `kind: "repository-component"` with its discovered `path` only when that runtime source is intentionally out of scope. Never use an omission merely to silence a warning.
 - Omit `meta.engineering_profile` by default. Region, cluster, and security boundary wording do not by themselves enable it. Enable `deployment-ownership` only when the user explicitly asks for a production deployment topology, ownership handoff, or fail-closed deployment review and the source facts are known. Once enabled, must not remove the engineering profile merely to pass validation; repair the facts or report the diagnostics truthfully.
 - Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; follow the label-preserving repair order.
 - Automatic routes own their endpoint sides. A side is a direction contract: the first and final segment must leave/enter perpendicular to that side.

archify/assets/template.html

@@ -4961,7 +4961,7 @@ <h1>[PROJECT NAME] Architecture</h1>
     </div>
 
     <!-- ARCHIFY:GUIDED_VIEWS_DATA -->
-    <!-- ARCHIFY:SOURCE_EVIDENCE_DATA -->
+    <!-- ARCHIFY:SOURCE_EVIDENCE_DATA -->    <!-- ARCHIFY:SEMANTIC_COVERAGE_DATA -->
     <!-- ARCHIFY:I18N_DATA -->
     <div class="guided-views no-print" id="guided-views" hidden aria-label="{{i18n:viewer.guided.region}}">
       <button id="guided-view-prev" type="button" aria-label="{{i18n:viewer.guided.previous}}" title="{{i18n:viewer.guided.previous.title}}">&#8592;</button>

archify/references/authoring-contract.md

@@ -186,6 +186,51 @@ configuration before authoring. Record only evidence you actually verified.
 dataflow, and lifecycle reject it. Never infer runtime causality from file
 proximity or naming alone.
 
+Translate that inspection into an explicit `semanticChecks` coverage ledger
+before arranging the diagram. When evidence is revision-pinned and verified,
+Archify also conservatively discovers lifecycle runtime candidates from tracked,
+non-test source paths containing `scheduler`, `cron`, `worker`, or `background`.
+Each candidate must be represented by a matching component (through its source
+path or identity) or explicitly omitted. Use `requiredComponents` for material runtime
+participants, including lifecycle schedulers and background workers;
+`requiredEdges` for direct calls or management paths; and `requiredPaths` for
+end-to-end flows that may contain intermediate components. Set
+`requireExternalLabels: true` when every external-system relationship must name
+its operation or protocol. The renderer embeds non-blocking
+`architecture/semantic-*` warnings in the HTML receipt so an incomplete draft
+remains inspectable. The same receipt keeps a requirement ledger: every checked
+component, edge, path, and external label is marked `represented`, `missing`,
+or `omitted` with concrete evidence. Review that ledger rather than treating a
+zero-warning summary as proof that the intended facts were actually checked.
+
+An intentional exclusion must be machine-readable in `omissions` and include a
+specific, non-whitespace reason. Kinds are `component`, `repository-component`,
+`edge`, `path`, and `external-label`; component omissions use `id`, discovered
+repository-component omissions use the exact repo-relative `path`, while
+relationship omissions use `from` and `to`. An omission documents scope; it is
+not evidence that a fact is absent.
+
+```json
+"semanticChecks": {
+  "requiredComponents": ["api", "scheduler", "external-mail"],
+  "requiredEdges": [{ "from": "api", "to": "dispatch" }],
+  "requiredPaths": [{ "from": "scheduler", "to": "external-mail" }],
+  "requireExternalLabels": true,
+  "omissions": [
+    {
+      "kind": "component",
+      "id": "legacy-worker",
+      "reason": "Out of scope: disabled by the inspected deployment configuration."
+    },
+    {
+      "kind": "repository-component",
+      "path": "src/legacy-worker.js",
+      "reason": "Out of scope: this migration-only worker is disabled in the inspected deployment."
+    }
+  ]
+}
+```
+
 ## Hand-placed fallback
 
 Use only when no renderer can run. Start from `assets/template.html`, keep semantic CSS classes, preserve the inline SVG/accessibility structure, and run the delivery visual checklist. Never introduce inline literal colors that break dark/light parity.

archify/renderers/architecture/render-architecture.mjs

@@ -10,6 +10,7 @@ import { brandLabelFitWidth, brandMetadataFor, brandTopRailProblem, renderBrandM
 import { minimumReadableSourceTextPx } from '../shared/desktop-readability.mjs';
 import { translateMessage as i18nText } from '../shared/i18n.mjs';
 import { gridLayout, resolveComponentPos, validateGridPlacement } from './grid.mjs';
+import { evaluateArchitectureSemanticCoverage } from './semantic-coverage.mjs';
 import {
   asArray,
   isFinitePoint,
@@ -58,6 +59,7 @@ const { diagram: arch, template, outPath, sourceEvidence } = await loadDiagramWi
   defaultExample: 'web-app.architecture.json',
   argv: cliArgs,
 });
+const semanticCoverage = evaluateArchitectureSemanticCoverage(arch, sourceEvidence?.semanticFacts);
 
 const grid = gridLayout(arch);
 
@@ -633,6 +635,7 @@ function buildLayoutReport() {
         return connectionPath(conn, routed, labelAt);
       }),
     labels,
+    semanticCoverage,
   };
 }
 
@@ -1075,4 +1078,5 @@ writeDiagram({
   svg: renderSvg(),
   cards: arch.cards,
   sourceEvidence,
+  semanticCoverage,
 });