dsh-knowhub 0.9.0 → 0.10.0

package/skills/archify/renderers/workflow/workflow-migration-geometry.mjs

@@ -0,0 +1,161 @@
+const TARGET_SCHEMA_VERSION = 2;
+
+// Planning removes absolute route assertions, but must keep the same rank
+// policy as the document whose coordinates will be mapped into that plan.
+// An authored canvas likewise keeps its established plan: draft-only optional
+// corridor growth must not consume space that a valid fixed canvas lacks.
+const absoluteGeometryPolicy = Symbol('workflow absolute geometry policy');
+export function preservesWorkflowAbsoluteGeometry(workflow) {
+  return workflow[absoluteGeometryPolicy] ?? (Array.isArray(workflow.meta?.viewBox) || (workflow.edges || []).some((edge) => (
+    Array.isArray(edge.via) || Array.isArray(edge.labelAt)
+    || edge.channelX !== undefined || edge.channelY !== undefined
+  )));
+}
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+/**
+ * Return the authored workflow as a schema-v2 document without its capacity
+ * override. The compiler can use this projection to discover the intrinsic v2
+ * rank plan before deciding whether an explicit viewBox needs to grow.
+ */
+export function intrinsicWorkflow(workflow) {
+  const intrinsic = clone(workflow);
+  intrinsic.schema_version = TARGET_SCHEMA_VERSION;
+  intrinsic[absoluteGeometryPolicy] = preservesWorkflowAbsoluteGeometry(workflow);
+  intrinsic.meta = { ...intrinsic.meta };
+  delete intrinsic.meta.viewBox;
+  return intrinsic;
+}
+
+/**
+ * Return a schema-v2 planning projection that removes authored route geometry
+ * which may only become valid after its legacy X coordinates are remapped.
+ * Rank-affecting automatic and straight relationships remain in the projection.
+ */
+export function planningWorkflow(workflow) {
+  const planned = intrinsicWorkflow(workflow);
+  planned.edges = planned.edges.flatMap((edge) => {
+    const hasRoutedGeometry = Array.isArray(edge.via)
+      || (edge.route && !['auto', 'straight'].includes(edge.route))
+      || edge.channelX !== undefined
+      || edge.channelY !== undefined;
+    if (hasRoutedGeometry) return [];
+
+    const automatic = {};
+    for (const property of ['id', 'from', 'to', 'variant', 'role', 'width']) {
+      if (edge[property] !== undefined) automatic[property] = edge[property];
+    }
+    if (edge.route === 'straight') automatic.route = 'straight';
+    if (edge.labelAt === undefined && edge.label !== undefined) automatic.label = edge.label;
+    return [automatic];
+  });
+
+  // Full-topology contracts cannot be checked against a layout-only subgraph.
+  // The source and final mapped candidate retain and validate these contracts.
+  if (planned.edges.length !== workflow.edges.length) delete planned.semanticChecks;
+
+  if (Array.isArray(planned.mainPath)) {
+    const projectedPairs = new Set(planned.edges.map((edge) => `${edge.from}\u0000${edge.to}`));
+    const projectionBreaksMainPath = planned.mainPath.some((from, index) => (
+      index < planned.mainPath.length - 1
+      && !projectedPairs.has(`${from}\u0000${planned.mainPath[index + 1]}`)
+    ));
+    if (projectionBreaksMainPath) delete planned.mainPath;
+  }
+
+  return planned;
+}
+
+function mappedNumber(value) {
+  return Number(value.toFixed(6));
+}
+
+/**
+ * Build a deterministic piecewise-linear mapping between corresponding legacy
+ * and readable rank centers. Coordinates outside the rank span are extrapolated
+ * using the nearest segment so explicitly authored outside corridors retain
+ * their relative offset.
+ */
+export function createHorizontalRankMapper(oldColumns, newColumns) {
+  if (
+    !Array.isArray(oldColumns)
+    || !Array.isArray(newColumns)
+    || oldColumns.length !== newColumns.length
+    || oldColumns.length < 2
+    || !oldColumns.every(Number.isFinite)
+    || !newColumns.every(Number.isFinite)
+  ) {
+    throw new TypeError('Horizontal rank mapping requires matching finite column arrays.');
+  }
+  for (let index = 1; index < oldColumns.length; index += 1) {
+    if (oldColumns[index] <= oldColumns[index - 1] || newColumns[index] <= newColumns[index - 1]) {
+      throw new TypeError('Horizontal rank mapping requires strictly increasing columns.');
+    }
+  }
+
+  return (x) => {
+    if (!Number.isFinite(x)) throw new TypeError('Horizontal rank mapping requires a finite x coordinate.');
+    let segment = oldColumns.length - 2;
+    if (x <= oldColumns[0]) {
+      segment = 0;
+    } else {
+      for (let index = 0; index < oldColumns.length - 1; index += 1) {
+        if (x <= oldColumns[index + 1]) {
+          segment = index;
+          break;
+        }
+      }
+    }
+    const oldSpan = oldColumns[segment + 1] - oldColumns[segment];
+    const newSpan = newColumns[segment + 1] - newColumns[segment];
+    const ratio = (x - oldColumns[segment]) / oldSpan;
+    return mappedNumber(newColumns[segment] + ratio * newSpan);
+  };
+}
+
+/**
+ * Apply one horizontal coordinate mapping to every schema-v1 absolute X pin.
+ * The caller owns the supplied workflow; this function reports an audit trail
+ * for each changed coordinate in stable document order.
+ */
+export function mapExplicitCoordinates(workflow, mapX) {
+  const changedCoordinates = [];
+  const record = (path, owner, property) => {
+    const from = owner[property];
+    const to = mapX(from);
+    owner[property] = to;
+    if (to !== from) changedCoordinates.push({ path, from, to });
+  };
+
+  for (const [edgeIndex, edge] of workflow.edges.entries()) {
+    if (Array.isArray(edge.via)) {
+      for (const [pointIndex, point] of edge.via.entries()) {
+        if (Array.isArray(point) && Number.isFinite(point[0])) {
+          record(`/edges/${edgeIndex}/via/${pointIndex}/0`, point, 0);
+        }
+      }
+    }
+    if (Array.isArray(edge.labelAt) && Number.isFinite(edge.labelAt[0])) {
+      record(`/edges/${edgeIndex}/labelAt/0`, edge.labelAt, 0);
+    }
+    if (Number.isFinite(edge.channelX)) {
+      record(`/edges/${edgeIndex}/channelX`, edge, 'channelX');
+    }
+  }
+  return changedCoordinates;
+}
+
+/**
+ * Construct an independently owned schema-v2 candidate with all authored
+ * absolute X pins mapped to the readable rank plan.
+ */
+export function createMappedWorkflowCandidate(workflow, oldColumns, newColumns) {
+  const document = clone(workflow);
+  document.schema_version = TARGET_SCHEMA_VERSION;
+  const mapX = createHorizontalRankMapper(oldColumns, newColumns);
+  const changedCoordinates = mapExplicitCoordinates(document, mapX);
+  return { document, changedCoordinates };
+}

package/skills/archify/renderers/workflow/workflow-placement-repair.mjs

@@ -0,0 +1,94 @@
+// One optional placement proposal for a failed readable workflow.
+// Never applied to the authored input; the compiler verifies the complete result.
+export function proposeWorkflowPlacement(input) {
+  if (input.schema_version !== 2 || input.meta?.viewBox
+    || input.groups?.length || input.phases?.length
+    || !input.mainPath?.length || input.nodes.length > 64
+    || input.edges.some(e => ['via', 'channelX', 'channelY', 'labelAt'].some(k => e[k] !== undefined))) {
+    return { eligible: false, reason: 'Needs unpinned v2, complete mainPath, no authored regions, <=64 nodes.' };
+  }
+  const main = input.mainPath;
+  const mainIndex = new Map(main.map((id, i) => [id, i]));
+  const nodes = new Map(input.nodes.map(n => [n.id, n]));
+  const laneIndex = new Map(input.lanes.map((l, i) => [l.id, i]));
+  if (main.some(id => !nodes.has(id)) || new Set(main).size !== main.length)
+    return { eligible: false, reason: 'Invalid mainPath.' };
+  const out = new Map(input.nodes.map(n => [n.id, input.edges.filter(e => e.from === n.id).map(e => e.to)]));
+  function reachable(id) {
+    const found = new Set(), todo = [...out.get(id)];
+    while (todo.length) {
+      const next = todo.pop();
+      if (found.has(next) || !nodes.has(next)) continue;
+      found.add(next); todo.push(...out.get(next));
+    }
+    return found;
+  }
+  const reach = new Map(input.nodes.map(n => [n.id, reachable(n.id)]));
+  const offMain = input.nodes.filter(n => !mainIndex.has(n.id));
+  const offIds = new Set(offMain.map(n => n.id));
+  const components = [], assigned = new Set();
+  for (const n of offMain) {
+    if (assigned.has(n.id)) continue;
+    const component = [], todo = [n.id];
+    while (todo.length) {
+      const id = todo.pop();
+      if (assigned.has(id)) continue;
+      assigned.add(id); component.push(id);
+      for (const e of input.edges) {
+        if (e.from === id && offIds.has(e.to)) todo.push(e.to);
+        if (e.to === id && offIds.has(e.from)) todo.push(e.from);
+      }
+    }
+    const cyclic = component.some(id => main.some(m => reach.get(id).has(m) && reach.get(m).has(id)));
+    components.push({ ids: component, cyclic });
+  }
+  const leftRail = components.some(c => c.cyclic);
+  if (!leftRail) return { eligible: false, reason: 'No return cycle connected to the main path.' };
+  const rightRail = components.some(c => !c.cyclic && c.ids.length > 1);
+  const start = leftRail ? 1 : 0, end = rightRail ? 4 : 5;
+  const proposed = structuredClone(input), moved = new Map(proposed.nodes.map(n => [n.id, n]));
+  let col = start;
+  for (let i = 0; i < main.length; i++) {
+    const current = moved.get(main[i]), previous = moved.get(main[i - 1]);
+    if (previous && laneIndex.get(current.lane) <= laneIndex.get(previous.lane)) col = Math.min(col + 1, end);
+    current.col = col;
+  }
+  for (const component of components) {
+    for (const id of component.ids) {
+      const n = moved.get(id);
+      const parents = input.edges.filter(e => e.to === id && mainIndex.has(e.from)).map(e => moved.get(e.from));
+      n.col = component.cyclic ? 0 : component.ids.length > 1 ? 5
+        : Math.min(end, Math.max(start, ...parents.map(p => p.col + 1)));
+      // Place same-lane failure branches below their main-path source row.
+      if (component.cyclic && parents.some(p => p.lane === n.lane)) {
+        const sameLane = main.map(m => moved.get(m)).filter(m => m.lane === n.lane);
+        n.yOffset = Math.max(...sameLane.map(m => (m.yOffset || 0) + (m.height || 52) / 2)) + (n.height || 52) / 2 + 40;
+      }
+    }
+  }
+  const groups = new Map();
+  for (const n of proposed.nodes) {
+    const key = n.lane + ':' + n.col;
+    groups.set(key, [...groups.get(key) || [], n]);
+  }
+  function order(n) {
+    if (mainIndex.has(n.id)) return mainIndex.get(n.id);
+    const incoming = input.edges.filter(e => e.to === n.id && mainIndex.has(e.from)).map(e => mainIndex.get(e.from));
+    return incoming.length ? Math.min(...incoming) + 0.5 : main.length;
+  }
+  for (const group of groups.values()) {
+    if (group.length < 2) continue;
+    group.sort((a, b) => order(a) - order(b) || a.id.localeCompare(b.id));
+    const total = group.reduce((sum, n) => sum + (n.height || 52), 0) + 40 * (group.length - 1);
+    let top = -total / 2;
+    for (const n of group) {
+      n.yOffset = top + (n.height || 52) / 2;
+      top += (n.height || 52) + 40;
+    }
+  }
+  const changes = [];
+  for (let i = 0; i < input.nodes.length; i++) for (const field of ['col', 'yOffset']) {
+    if (input.nodes[i][field] !== proposed.nodes[i][field]) changes.push({op: field in input.nodes[i] ? 'replace' : 'add', path: `/nodes/${i}/${field}`, value: proposed.nodes[i][field]});
+  }
+  return {eligible: true, proposed, changes, components, rails: {left: leftRail, right: rightRail}};
+}

package/skills/archify/schemas/README.md

@@ -0,0 +1,258 @@
+# Archify JSON IR Schemas
+
+Each typed renderer consumes a JSON intermediate representation (IR) validated
+against one of the schemas in this folder before any layout work happens.
+
+## Files
+
+| Schema | Governs | Structural arrays |
+|--------|---------|-------------------|
+| `workflow.schema.json` | `diagram_type: "workflow"` | `lanes`, `phases`, `groups`, `mainPath`, `nodes`, `edges` |
+| `sequence.schema.json` | `diagram_type: "sequence"` | `participants`, `segments`, `messages`, `activations` |
+| `dataflow.schema.json` | `diagram_type: "dataflow"` | `stages`, `nodes`, `flows` |
+| `lifecycle.schema.json` | `diagram_type: "lifecycle"` | `mainPath`, `states`, `transitions` |
+| `architecture.schema.json` | `diagram_type: "architecture"` | `components`, `boundaries`, `connections` |
+| `erd.schema.json` | `diagram_type: "erd"` | `entities`, `relationships` |
+| `tree.schema.json` | `diagram_type: "tree"` | `nodes` (each with one `parent`) |
+| `class.schema.json` | `diagram_type: "class"` | `types`, `relationships` |
+| `timeline.schema.json` | `diagram_type: "timeline"` | `events` (`lanes` optional) |
+| `waterfall.schema.json` | `diagram_type: "waterfall"` | `spans` (each with optional `parent`) |
+| `common.schema.json` | shared `$defs` only (no top-level document) | — |
+
+Every diagram schema requires `schema_version`, `diagram_type`, `meta` (with
+`title` and a durable portable `output`), and its structural arrays — except `segments`, `activations`, ERD and class
+`relationships`, and `cards`, which are optional — and sets `additionalProperties: false` at every
+level, so unknown fields are rejected rather than silently ignored.
+
+Every `meta` object also accepts `animation: "trace"` for opt-in SVG/CSS motion
+in generated HTML. Omit it, or set `"none"`, for the default static output.
+It also accepts `locale`, any well-formed language tag (schema pattern
+`^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$`). The field selects the fixed Viewer UI,
+renderer-owned default legend and accessibility copy, document-title suffix,
+and `<html lang>` value; it does not translate authored strings. The bundled
+catalogs enrolled in `locales/manifest.json` (`en`, `zh-CN`, `zh-TW`, `es`, `ko`, `ar`) are
+selected by tag, case-insensitively; region and script variants are distinct
+tags. Any other tag needs a matching `translations` object (see below) or the
+renderer falls back to English and discloses it.
+Omitting `locale` preserves legacy behavior and resolves to English.
+Malformed locale tags fail schema validation instead of being guessed or
+silently rewritten.
+
+`meta.translations` is an optional per-key override, as data: an object mapping
+canonical message keys (`locales/en.json`) to translated strings whose
+`{placeholder}` tokens match the English source. Each message resolves as:
+valid `translations` value → bundled catalog for `locale` → English. An
+unrecognized key or mismatched placeholders never replaces a valid
+lower-priority message and fails no render; `validate`/`render`/`deliver`
+report rejected entries and the final resolved coverage to stderr.
+`visual_preset` accepts `classic` (the stable default), `signal-flow` (luminous
+motion-forward presentation), `blueprint` (high-contrast engineering review),
+or `editorial` (warm publication-style design review and documentation).
+Presets change only viewer styling; they do not alter semantic IDs or geometry.
+Sequence `meta` additionally accepts `column_fit`. The default `spread` applies whether or not `meta.viewBox` is supplied.
+Explicit `fixed` keeps the historical 108px column gap and 86px participant
+boxes. `spread` derives column distance and box width from the viewBox, with
+at least a 16px gutter between participant cards, which turns a
+wide canvas into column distance and label room rather than empty space on the
+right. Lane order, IDs, and message semantics are unchanged either way.
+
+`meta.views` is retired. The schemas still accept the old guided-view shape so
+existing files keep validating, but renderers ignore it; do not author it.
+
+### Legend presentation contract
+
+Every `meta` object accepts the same optional legend shape without changing
+the schema version already selected for that renderer:
+
+```json
+"legend": {
+  "mode": "auto",
+  "entries": {
+    "security": { "label": "restricted data", "visible": true }
+  }
+}
+```
+
+`mode` is `auto` (the default), `all`, or `hidden`. `auto` includes only kinds
+present in typed IR; `all` includes the renderer's full stable catalog;
+`hidden` removes the complete legend and takes precedence over entry overrides.
+Architecture documents that omit an explicit `viewBox` size that automatic
+viewBox from the same measured resolved legend footprint used for final SVG
+layout. Across all renderers, legacy documents that omit `meta.legend` use a
+compatibility-safe implicit `auto`: if the resolved legend cannot fit an
+explicit authored viewBox without overlap, Archify omits the complete legend
+instead of turning a previously valid schema-v1 document into a hard failure.
+Once an author adds `meta.legend` (including explicit `mode: "auto"`), the
+layout is intentional and unfit labels or bands fail with a path-prefixed
+diagnostic. An entry may set a non-empty, bounded `label`, boolean `visible`,
+or both.
+`visible: false` removes a resolved entry and `visible: true` forces a supported
+but unused kind into the visual legend. Unknown kinds and properties fail
+strict validation.
+
+Supported keys are renderer-owned:
+
+| Renderer | `meta.legend.entries` keys |
+|---|---|
+| Architecture | `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external` |
+| Workflow | `frontend`, `backend`, `security`, `messagebus`, `database`, `cloud`, `external` |
+| Sequence | `emphasis`, `return`, `security`, `dashed`, `default` |
+| Dataflow | `emphasis`, `security`, `dashed`, `database`, `default` |
+| Lifecycle | `start`, `active`, `waiting`, `decision`, `success`, `failure`, `neutral`, `external` |
+| ERD | `pk`, `fk`, `uk`, `one`, `many`, `optional` |
+| Class | `dependency`, `association`, `inheritance`, `realization`, `composition`, `aggregation` |
+
+Labels are presentation only: they do not rename the stable kind, change
+nodes/relationships, or create Semantic Lens edge facts. Sequence message and
+Dataflow flow-variant entries are visual keys. Component/state entries backed
+by exact compiled node facts receive the interactive Semantic Legend bridge;
+this includes Dataflow `database` when a real `nodes[].type: "database"` fact
+exists.
+
+Every relationship collection (`connections`, `edges`, `messages`, `flows`, and
+`transitions`) accepts an optional author-controlled `id` using the shared ID
+pattern. The renderer keeps its source-order runtime key separately, while the
+authored ID enables a stable `#relation=<id>` viewer link that survives array
+reordering. ID-less documents remain valid and their relationship pins stay
+local to the current page.
+
+Every semantic node collection (`components`, `nodes`, `participants`, and
+`states`) also accepts one optional `brand`: either a canonical string returned
+by `archify brands --json`, or a digest-pinned `{ "url", "sha256" }` object
+returned by `archify brands capture <url> --json`. Known IDs and known-brand
+domains use the bundled vector catalogue. Unknown URLs must be captured in that
+explicit command before authoring; render and validate never perform an
+unpinned network capture. Unsafe, unavailable, changed, or unsupported content
+fails closed with a brand diagnostic. Omitted `brand` preserves the prior
+output.
+
+## schema_version policy
+
+Workflow supports schema versions 1 and 2. Version 1 remains the fixed-layout
+compatibility contract; version 2 opts into the readable workflow compiler and
+can be produced explicitly with `archify migrate workflow ... --to-schema 2`.
+Lifecycle accepts only version 3, an automatic main-path layout (see the
+[lifecycle renderer](../renderers/lifecycle/README.md)).
+The other three diagram schemas keep `schema_version` pinned to `1`; they have
+no schema-version migration command. For any of the five diagram types, repair
+a legacy missing or nonportable `meta.output` in the source and run `validate`.
+For a workflow v1-to-v2 migration specifically, `migrate workflow` also accepts
+`--output reports/diagram.html` to put that portable value in the separate v2
+destination without changing the legacy source.
+
+Workflow also accepts optional `semanticChecks`. `allowedRoots` and
+`allowedTerminals` close the set of intentional graph sources and sinks;
+`requiredEdges` requires exact authored relationships; and `requiredPaths`
+requires directed reachability while allowing intermediate nodes. The compiler
+evaluates these facts before layout and returns typed `workflow/*` diagnostics.
+The field is additive and geometry-neutral: omitting it preserves existing
+workflow behavior and including a satisfied contract does not change SVG or
+layout-receipt bytes.
+
+A file that validates today must keep validating and rendering within its
+declared version throughout the 2.x release line. The explicitly reviewed
+portable-output hardening is the one exception: older v1 documents that omit
+`meta.output` must add a portable POSIX-relative `.html` path (for example,
+`reports/diagram.html`); ordinary explicit CLI output arguments do not replace
+this durable authored value. The workflow-only v1-to-v2 migration command may
+instead receive that value explicitly as `--output reports/diagram.html`; it
+writes the value only to its separate validated destination. Additive viewer,
+accessibility, and presentation improvements may enhance generated HTML, but
+they must not reinterpret authored IR or turn a previously valid profile-less
+v1 file into a new hard layout failure. Breaking IR changes require a new
+version; additive, backwards-compatible fields do not.
+
+## Shared definitions (common.schema.json)
+
+The five diagram schemas reference `common.schema.json#/$defs/...`:
+
+- `id` — element identifiers, pattern `^[a-zA-Z][a-zA-Z0-9_-]*$`
+- `point` — an `[x, y]` pair of numbers (used by `via` and `labelAt`)
+- `componentType` — `frontend`, `backend`, `database`, `cloud`, `security`,
+  `messagebus`, `external`
+- `locale` — a well-formed renderer locale tag (bundled catalogs are listed in
+  `locales/manifest.json`; any other tag needs a matching `translations` object)
+- `translations` — canonical message key → translated string, layered over the
+  bundled catalog for `locale`, then English
+- `portableOutputPath` — the portable POSIX-relative `.html` path used by
+  `meta.output`; see the two output-path boundaries in the
+  [delivery contract](../references/delivery-contract.md#output-path-contracts)
+- `brandMark` — one optional built-in brand ID or explicit HTTP(S) site URL
+- `variant` — `default`, `emphasis`, `security`, `dashed` (sequence messages
+  extend this list locally with `return`)
+- `legendMode` and `legendEntry` — the shared strict mode and label/visibility
+  override shapes used by each renderer-owned key map
+- `guidedViews` — the retired `meta.views` shape, still accepted and ignored
+- `cards` — the summary-card blocks rendered below the SVG
+
+Lifecycle state `type` is mode-specific (`start`/`active`/`waiting`/...) and
+stays in `lifecycle.schema.json`.
+
+The JSON Schema definition is the portable contract's structurally expressible
+preflight. The shipped generated validator wrapper and CLI additionally enforce
+byte-based component limits and the complete runtime path contract; consumers
+that need the same cross-platform acceptance boundary should use that wrapper.
+
+## Runtime validation
+
+At development time, `scripts/generate-validators.mjs` compiles all five
+schemas with ajv's draft 2020-12 standalone generator using `strict: true` and
+`allErrors: true`. The generated `renderers/shared/generated-validators.mjs`
+is committed and shipped with the skill, so runtime validation has no npm or
+network dependency. `renderers/shared/validator.mjs` applies the matching
+standalone validator before the renderer's own layout checks.
+The shared loader then checks cross-collection facts that JSON Schema cannot
+express cleanly here: duplicate view IDs, duplicate focus IDs, focus IDs that do
+not exist in the diagram's semantic collection, and duplicate authored
+relationship IDs within the mode's relationship collection.
+
+All five modes support opt-in, revision-pinned repository evidence.
+`meta.repository` names the repository URL and full commit SHA, with optional
+`provider` (`github`, `gitee`, or `gitlab`) and `link_mode` (`web` or `local-only`; see the
+authoring contract); a node may carry one to three `sources` with repo-relative POSIX paths, optional line
+ranges, and optional labels. Sources are authored on the mode's own node
+collection — Architecture `components`, Workflow and Data Flow `nodes`,
+Sequence `participants`, Lifecycle `states` — and the verified payload is keyed
+by node id. Shape is schema-checked, then the renderer requires
+`--repo-root`: the local Git origin must match, and Git must prove the commit,
+blobs, and requested lines. Verified evidence is embedded outside the canonical
+SVG for the Semantic Passport and Node Finder; ordinary documents and visual
+exports carry no repository evidence.
+
+## Visual quality and engineering truth
+
+`meta.quality_profile` and `meta.engineering_profile` answer different
+questions. `quality_profile` is available in all five modes and controls how
+strictly Archify judges composition. `engineering_profile` is an optional
+Architecture-only semantic contract; omitting it preserves the ordinary v1
+behavior.
+
+The first engineering profile is `deployment-ownership`. Enable it only when
+the user wants a fail-closed deployment review and the source facts are known.
+It requires every non-external component to name an owner in `tag` and belong
+to exactly one `region`; the document must contain both `region` and
+`security-group` boundaries; every `database` must be inside a
+`security-group`; each security group must contain members from one shared
+region; and every connection whose region or security-group membership changes
+must name the real crossing mechanism in `label`.
+
+The profile validates only authored IR. It does not discover infrastructure,
+infer owners, or prove that a diagram matches a live environment. If a fact is
+unknown, leave the profile unset or obtain the fact instead of inventing it.
+
+`npm test` runs the generator in check mode and fails when the committed
+validators drift from their schemas.
+
+## Error format
+
+Schema violations exit non-zero. Each ajv error is reported on its own line as
+the instance path — annotated with the nearest enclosing element's `id` or
+`label` — followed by the message and parameters:
+
+```text
+workflow schema validation failed:
+  /nodes/3 (id/label: "router") must NOT have additional properties {"additionalProperty":"colour"}
+```
+
+Schemas catch shape errors (types, enums, ranges, unknown fields); geometry
+problems such as overlaps and label collisions are the renderers' job.

package/skills/archify/schemas/architecture.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/tt-a1i/archify/schemas/architecture.schema.json",
+  "title": "Archify Architecture Diagram",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "diagram_type", "meta", "components"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "diagram_type": { "const": "architecture" },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title", "output"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "locale": { "$ref": "common.schema.json#/$defs/locale" },
+        "translations": { "$ref": "common.schema.json#/$defs/translations" },
+        "subtitle": { "type": "string" },
+        "output": { "$ref": "common.schema.json#/$defs/portableOutputPath" },
+        "animation": { "$ref": "common.schema.json#/$defs/animation" },
+        "visual_preset": { "$ref": "common.schema.json#/$defs/visualPreset" },
+        "quality_profile": { "$ref": "common.schema.json#/$defs/qualityProfile" },
+        "engineering_profile": { "enum": ["deployment-ownership"] },
+        "repository": { "$ref": "common.schema.json#/$defs/repository" },
+        "views": { "$ref": "common.schema.json#/$defs/guidedViews" },
+        "legend": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": { "$ref": "common.schema.json#/$defs/legendMode" },
+            "entries": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "frontend": { "$ref": "common.schema.json#/$defs/legendEntry" },
+                "backend": { "$ref": "common.schema.json#/$defs/legendEntry" },
+                "database": { "$ref": "common.schema.json#/$defs/legendEntry" },
+                "cloud": { "$ref": "common.schema.json#/$defs/legendEntry" },
+                "security": { "$ref": "common.schema.json#/$defs/legendEntry" },
+                "messagebus": { "$ref": "common.schema.json#/$defs/legendEntry" },
+                "external": { "$ref": "common.schema.json#/$defs/legendEntry" }
+              }
+            }
+          }
+        },
+        "viewBox": {
+          "type": "array",
+          "prefixItems": [
+            { "type": "number", "minimum": 320 },
+            { "type": "number", "minimum": 240 }
+          ],
+          "items": false,
+          "minItems": 2,
+          "maxItems": 2
+        }
+      }
+    },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": { "enum": ["grid"] },
+        "origin": { "$ref": "common.schema.json#/$defs/point" },
+        "cols": { "type": "integer", "minimum": 1, "maximum": 12 },
+        "gapX": { "type": "number", "minimum": 0 },
+        "gapY": { "type": "number", "minimum": 0 },
+        "cellW": { "type": "number", "minimum": 40 },
+        "cellH": { "type": "number", "minimum": 24 }
+      }
+    },
+    "components": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "type", "label"],
+        "properties": {
+          "id": { "$ref": "common.schema.json#/$defs/id" },
+          "type": { "$ref": "common.schema.json#/$defs/componentType" },
+          "label": { "type": "string", "minLength": 1 },
+          "sublabel": { "type": "string" },
+          "tag": { "type": "string" },
+          "icon": { "$ref": "common.schema.json#/$defs/nodeIcon" },
+          "brand": { "$ref": "common.schema.json#/$defs/brandMark" },
+          "sources": { "$ref": "common.schema.json#/$defs/sourceReferences" },
+          "row": { "type": "integer", "minimum": 0 },
+          "col": { "type": "integer", "minimum": 0 },
+          "pos": { "$ref": "common.schema.json#/$defs/point" },
+          "size": {
+            "type": "array",
+            "prefixItems": [
+              { "type": "number", "exclusiveMinimum": 0 },
+              { "type": "number", "exclusiveMinimum": 0 }
+            ],
+            "items": false,
+            "minItems": 2,
+            "maxItems": 2
+          }
+        }
+      }
+    },
+    "boundaries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "label", "wraps"],
+        "properties": {
+          "kind": { "enum": ["region", "security-group"] },
+          "label": { "type": "string", "minLength": 1 },
+          "wraps": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "common.schema.json#/$defs/id" }
+          },
+          "pad": { "type": "number", "minimum": 0 }
+        }
+      }
+    },
+    "connections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["from", "to"],
+        "properties": {
+          "id": { "$ref": "common.schema.json#/$defs/id" },
+          "from": { "$ref": "common.schema.json#/$defs/id" },
+          "to": { "$ref": "common.schema.json#/$defs/id" },
+          "label": { "type": "string" },
+          "variant": { "$ref": "common.schema.json#/$defs/variant" },
+          "fromSide": { "$ref": "common.schema.json#/$defs/side" },
+          "toSide": { "$ref": "common.schema.json#/$defs/side" },
+          "route": { "enum": ["auto", "straight", "orthogonal-h", "orthogonal-v"] },
+          "via": {
+            "type": "array",
+            "items": { "$ref": "common.schema.json#/$defs/point" }
+          },
+          "labelAt": { "$ref": "common.schema.json#/$defs/point" },
+          "labelDx": { "type": "number" },
+          "labelDy": { "type": "number" },
+          "labelSegment": { "type": "integer", "minimum": 0 },
+          "width": { "$ref": "common.schema.json#/$defs/relationshipWidth" }
+        }
+      }
+    },
+    "cards": { "$ref": "common.schema.json#/$defs/cards" }
+  }
+}