dsh-archify-projects 0.0.0-stage → 0.1.0

package/skills/archify/references/repository-authoring.md

@@ -0,0 +1,105 @@
+# Repository-backed architecture authoring
+
+Use this reference when a diagram must explain a real repository. The source is
+the authority for responsibilities, calls, boundaries, and persistence. The
+diagram is complete when the requested meaning is covered and every asserted
+fact has supporting source evidence.
+
+## Explore on demand
+
+1. **Freeze identity.** From the target repository, record `git rev-parse
+   HEAD`, `git remote get-url origin`, and `git status --short`. Remove HTTP(S)
+   userinfo (including usernames, passwords, and tokens) before recording the
+   origin or placing it in the candidate. Preserve its transport, port, path and
+   `.git` suffix; do not rewrite an internal SSH origin as HTTPS. Pin the credential-free URL and
+   forty-character revision in `meta.repository`. Use `link_mode: "local-only"`
+   for an SSH origin, unsupported forge, intentionally local-only source links,
+   or a local fixture whose HTTPS URL is only a repository identity; retain the
+   URL and revision. Web links require a supported GitHub or Gitee HTTPS origin. If the
+   worktree is dirty, record the changed paths. Repository evidence is verified
+   against committed bytes at the pinned revision, not working-tree edits:
+   inspect a clean checkout at that revision for any cited changed path. Do not
+   present uncommitted bytes as evidence for `HEAD`; `local-only` does not record
+   a verifiable snapshot of those bytes.
+
+2. **Map the slice.** Use project instructions, manifests, entry points,
+   registrations, and deployment configuration to locate candidate runtime
+   units. Read the entry, configuration, and modules relevant to the request.
+   Follow imports and call sites
+   until the requested responsibility reaches its actual input, output, or
+   side effect. Read a small connected slice instead of scanning the repository
+   for a convenient label.
+
+3. **Trace ownership.** Derive runtime and I/O relationships from the observed
+   actor, operation, and target at their call sites; deployment and trust
+   relationships use the corresponding configuration or enforcement evidence. Distinguish the controller requesting
+   an operation from the runtime that executes it and the store receiving bytes.
+   For a file or database edge, the source must identify its actual reader or
+   writer; a responsibility statement such as “maintains tasks” does not prove
+   direct I/O. Keep these facts with the source locations while reading, without
+   a separate planning artifact. Choose which distinctions need separate
+   nodes using [Composition and meaning](authoring-defaults.md#composition-and-meaning);
+   discovering an implementation role does not automatically add it to the overview.
+   A configured provider, an injected adapter, a local stub, and a durable
+   service are different claims; label the one the source supports.
+
+4. **Record evidence while reading.** Keep exact repository-relative paths and
+   inclusive line ranges for each component and meaningful relationship. Follow
+   actual branches, retries, fallbacks, and error handling. A function that is
+   exported or configured but never called by the normal path is an optional
+   capability, not a required runtime edge. For a claim about authoritative
+   state change or control ownership, trace to the actual write or execution
+   site and the conditions that permit it; an upstream caller alone does not
+   establish those conditions.
+
+5. **Name uncertainty.** Write unresolved questions beside the claim they
+   affect: for example, “`writeFile` is called here; durability is unknown.”
+   Resolve a question by reading the next relevant source range or preserve it
+   as an explicit unknown. Never turn a label, package description, or config
+   value into an unobserved service or behavior.
+
+Stop exploring when every requested responsibility, relationship, and boundary
+has supporting source entailment and the remaining unknowns cannot change that
+coverage. There is no node, edge, citation, view, card, or boundary count to
+hit. Do not add a summary step merely to signal completion.
+
+Batch independent relevant files when known. Each additional read should answer
+an unresolved question that can change the diagram. Reuse concise facts and
+their source ranges already verified in this task; across revisions, recheck
+the affected entry points, configuration, dependencies, and evidence.
+
+## Choose an example by structure
+
+Select the main example in the [Type router](../SKILL.md#type-router) before
+loading its content, using the request and repository metadata already needed
+for source inspection. Selection fits the existing read batch and needs no extra
+message, command, or repository-wide scan. For mixed or unclear tasks, use the
+requested responsibilities and entry points as they become known in normal
+inspection; keep their actual roles. Read another example when a necessary
+capability remains unexplained. Examples teach shape, not facts: a library need
+not acquire filesystem nodes, and finished showcases still follow the
+first-draft automatic-routing rule.
+
+## Author from evidence
+
+Use the mode's complete JSON shape, including repository identity,
+components, and connections; every repository-backed component needs supporting source
+references, while boundaries or cards are added only when they
+answer a real reader question. Let automatic routes and automatic
+viewBox sizing work first. Keep the primary path readable, put exception paths
+beside their owner, and leave filesystem stores outside a control boundary when
+the source shows a separate responsibility.
+
+An existing example teaches field shape, not facts or arbitrary values. It does
+not authorize a new boundary kind, a long note, a viewBox size, or a route
+control. Consult the specific mode schema and `schemas/common.schema.json`
+whether or not the selected example already contains the field; use the
+schema's enum, length, identifier, and repository rules. Architecture
+boundaries currently use `kind: "region"` or `kind: "security-group"`; source
+references use `path`, `line`, and optional `end_line`.
+
+Repository-backed components need concise, truthful `sources` references. Preserve
+control ownership when summarizing filesystem I/O: the code that reads or writes
+a file owns that action, while a pure in-memory transform receives and returns
+values. This fact-check does not require a separate overview node for every helper. Use the existing examples for valid field shape, then replace all
+identifiers, wording, source paths, and claims with inspected repository facts.

package/skills/archify/references/update-awareness.md

@@ -0,0 +1,12 @@
+# Update awareness
+
+Read this file when a `finalize` or standalone `deliver` receipt has `update.noticeRequired: true`.
+
+Keep one compact line in the final response, in the user's language, with `installedVersion`, `availableVersion`, and the official `releaseNotes` link. Say that the installed Skill has not changed and that the user can ask to snooze or ignore the reminder. If `source` is `cache`, say that a previous check at `checkedAt` found the update. A process message or tool output does not replace this final line.
+For `severity: "security"`, label it as a security update without making installation automatic or urgent by default.
+
+You may translate the fixed local `noticeText`. Never quote, summarize, or translate the remote manifest's summary.
+
+When the user explicitly asks to pause or stop this reminder, run `node scripts/check-update.mjs --snooze "<eventKey>"` (seven days) or `--ignore "<eventKey>"` (this exact release only) from the Skill directory with the receipt's `update.eventKey`, then report the returned status. Never run them on your own initiative; `--ack` is a no-op. These commands do not install an update, and a newer release notifies again.
+
+The notice is information, not permission. Keep the installed version unchanged. This workflow never downloads, installs, or executes an update, and silence is never consent.

package/skills/archify/references/viewer-runtime.md

@@ -0,0 +1,35 @@
+# Viewer Runtime reference
+
+Read this only when the user asks for a reader-facing capability. Ordinary generation does not require implementing or re-documenting these features; they are already in the generated HTML.
+
+## Exploration
+
+- Diagram Guide lists current actions and shortcuts.
+- Reading Depth starts at READ at the default 100% scale, reveals FULL detail at 175%, and falls back to MAP only below 100%. Focus, route, and semantic interactions reveal their exact facts at any scale.
+- Semantic Lens summarizes selected node/relationship kinds without changing authored geometry.
+- Intent Trace previews a fine-pointer or keyboard target before committed focus.
+- Node Finder searches labels and stable IDs.
+- Semantic Passport opens on focus, shows authored upstream/downstream facts, supports a copyable deep link, has an explicit close action, closes on true outside activation and Escape, and never enters canonical export.
+- Semantic Radar mirrors the visible viewport and authored graph without becoming a second source of truth.
+- Direct Relationship Pin makes a unique compiled relationship operable while preserving the authored line and stable relationship identity. It must fail closed on conflicting source/target/label/ID metadata.
+- Route Probe resolves exactly two endpoints over authored directed relationships. It never infers a route from geometry.
+
+## Motion and presentation
+
+`meta.animation: "trace"` enables a finite reader-controlled Live/Still trace. Static is the default. Still, reduced motion, page hiding, print, and canonical export preserve complete static meaning. Presentation Stage changes viewer chrome and framing, never authored geometry. This is not a mobile product feature; narrow layouts get containment only.
+
+## Canonical exports
+
+The export menu can copy/download full-diagram PNG, download JPEG/WebP, download a dual-theme SVG, and record a trace-enabled WebM. Viewer state—Guide, Lens, finder, focus, route, camera, radar, presentation, motion ownership, and temporary overlays—must be removed from canonical export.
+
+### Route Share Card
+
+After a real directed Route Probe resolves, the reader may use **Export → Route Share Card**. It reuses the exact ordered route snapshot and the shared Share Card seam: `format=share-card`, `variant=route`. The isolated clone may use only static `data-share-route-*` decoration. It is download-only, fails closed for stale/unreachable/conflicting routes, and never becomes the canonical artifact.
+
+### Reach Share Card
+
+After a non-empty authored reachability query, the reader may use **Export → Reach Share Card**. It consumes the already resolved upstream/downstream node and edge set without rerunning traversal: `format=share-card`, `variant=reach`. The isolated clone may use only static `data-share-reach-*` decoration. It is download-only. Call it authored reachability—not impact, blast radius, breakage, or runtime causality.
+
+## Truth boundary
+
+Viewer exports are communication assets. They do not replace the checked HTML, the deterministic delivery receipt, or a real visual review. Do not add a hosted service, storage surface, dependency, schema branch, or mobile product surface for these viewer-only capabilities.

package/skills/archify/renderers/architecture/grid.mjs

@@ -0,0 +1,62 @@
+/** Grid placement for architecture IR (#8). Not auto-layout — fixed cell math only. */
+
+export const DEFAULT_GRID = {
+  mode: 'grid',
+  origin: [40, 80],
+  cols: 4,
+  gapX: 30,
+  gapY: 40,
+  cellW: 130,
+  cellH: 64,
+};
+
+export function gridLayout(arch) {
+  const raw = arch.layout;
+  if (!raw || raw.mode !== 'grid') return null;
+  return { ...DEFAULT_GRID, ...raw };
+}
+
+export function resolveComponentPos(component, grid) {
+  if (Array.isArray(component.pos) && component.pos.length === 2) {
+    return component.pos;
+  }
+  if (!grid) return [NaN, NaN];
+  if (!Number.isInteger(component.row) || !Number.isInteger(component.col)) {
+    return [NaN, NaN];
+  }
+  const [ox, oy] = grid.origin;
+  const stepX = grid.cellW + grid.gapX;
+  const stepY = grid.cellH + grid.gapY;
+  return [ox + component.col * stepX, oy + component.row * stepY];
+}
+
+export function validateGridPlacement(arch, grid, problems) {
+  if (!grid) return;
+  if (arch.layout !== undefined && arch.layout.mode !== 'grid') {
+    problems.push('layout.mode must be "grid" when layout is set (free placement omits layout entirely).');
+    return;
+  }
+  const seen = new Map();
+  for (const c of arch.components ?? []) {
+    const hasPos = Array.isArray(c.pos) && c.pos.length === 2;
+    const hasCell = Number.isInteger(c.row) && Number.isInteger(c.col);
+    if (hasPos) continue; // pos wins; row/col are optional hints only
+    if (!hasPos && !hasCell) {
+      problems.push(`Component "${c.id}" needs pos [x,y] or grid row/col when layout.mode is "grid".`);
+      continue;
+    }
+    if (c.row < 0 || c.col < 0) {
+      problems.push(`Component "${c.id}" row/col must be non-negative integers.`);
+      continue;
+    }
+    if (c.col >= grid.cols) {
+      problems.push(`Component "${c.id}" col ${c.col} exceeds layout.cols ${grid.cols} (valid: 0..${grid.cols - 1}).`);
+    }
+    const key = `${c.row},${c.col}`;
+    if (seen.has(key)) {
+      problems.push(`Components "${seen.get(key)}" and "${c.id}" share grid cell row ${c.row} col ${c.col}.`);
+    } else {
+      seen.set(key, c.id);
+    }
+  }
+}

package/skills/archify/renderers/architecture/labels.mjs

@@ -0,0 +1,215 @@
+import { normalizeRoutePoints, rectsOverlap, segmentRectClearanceWithin } from '../shared/geometry.mjs';
+import { createSpatialGrid } from '../shared/spatial-grid.mjs';
+
+// A bounded fallback for an unpinned label whose usual position collides.
+// It never routes an edge, moves a node, expands the canvas, or rewrites input.
+export function placeAutomaticLabels({
+  labels, routes, components, titles, viewBox, placementBottom = viewBox[1], fallbackRing = true, keepFallbackNearRoute = false,
+  gridSweep = false,
+}) {
+  const placed = [...labels];
+  const obstacles = [...components, ...titles];
+  const segments = routes.flatMap(({ relationIndex, points }) => {
+    const normalized = normalizeRoutePoints(points);
+    return normalized.slice(1).map((end, index) => ({ relationIndex, start: normalized[index], end }));
+  });
+  const inside = rect => (
+    rect.x >= 0 && rect.y >= 0
+    && rect.x + rect.width <= viewBox[0] && rect.y + rect.height <= viewBox[1]
+  );
+  // The mask test asked every segment about every candidate position. Segments
+  // go into a uniform grid once, and a candidate only asks the cells it covers.
+  const SEGMENT_CELL = 120;
+  const segmentGrid = createSpatialGrid(SEGMENT_CELL);
+  for (const segment of segments) {
+    const [sx, sy] = segment.start;
+    const [ex, ey] = segment.end;
+    segmentGrid.insert({
+      minX: Math.min(sx, ex), maxX: Math.max(sx, ex),
+      minY: Math.min(sy, ey), maxY: Math.max(sy, ey),
+    }, segment);
+  }
+  const segmentsNear = (rect, margin) => segmentGrid.query({
+    minX: rect.x - margin, maxX: rect.x + rect.width + margin,
+    minY: rect.y - margin, maxY: rect.y + rect.height + margin,
+  });
+  const masksRoute = rect => {
+    for (const segment of segmentsNear(rect, 4)) {
+      if (segment.relationIndex === rect.relationIndex) continue;
+      if (segmentRectClearanceWithin(segment, rect, 4) + 0.0001 < 4) return true;
+    }
+    return false;
+  };
+  const overlapsLabel = (rect, index, gap = 0) => placed.some((other, otherIndex) => (
+    otherIndex !== index && rectsOverlap(rect, other, gap)
+  ));
+  const clear = (rect, index) => (
+    inside(rect) && rect.y + rect.height <= placementBottom
+    && !obstacles.some(obstacle => rectsOverlap(rect, obstacle, 2))
+    && !overlapsLabel(rect, index, 2) && !masksRoute(rect)
+  );
+  const rectAt = (label, lx, ly) => ({
+    ...label, lx, ly, x: lx - label.width / 2, y: ly - 10,
+  });
+  // An opted-in grid layout runs parallel lines through shared gaps. Rank
+  // every position along all of the label's own segments: beside the line
+  // first, then centred on its own line (the plate interrupts only that
+  // line), then stepping outward past neighbouring parallels.
+  const gridCandidates = (label) => {
+    const fractions = [0.5, 0.25, 0.75, 0.375, 0.625, 0.125, 0.875];
+    const ranked = [];
+    // A close parallel of another relationship on one side (a reciprocal
+    // pair) makes a label on that side read as the neighbour's: prefer the
+    // far side.
+    const parallelOnLowSide = (a, b, axis) => {
+      const across = 1 - axis;
+      const [low, high] = [Math.min(a[axis], b[axis]), Math.max(a[axis], b[axis])];
+      let nearest = null;
+      for (const other of segments) {
+        if (other.relationIndex === label.relationIndex) continue;
+        if (Math.abs(other.start[across] - other.end[across]) > 0.0001) continue;
+        const distance = other.start[across] - a[across];
+        if (Math.abs(distance) < 0.0001 || Math.abs(distance) > 36) continue;
+        const overlap = Math.min(high, Math.max(other.start[axis], other.end[axis]))
+          - Math.max(low, Math.min(other.start[axis], other.end[axis]));
+        if (overlap <= 0) continue;
+        if (nearest === null || Math.abs(distance) < Math.abs(nearest)) nearest = distance;
+      }
+      return nearest !== null && nearest < 0;
+    };
+    for (const { start: a, end: b } of segments.filter(segment => segment.relationIndex === label.relationIndex)) {
+      if (Math.abs(a[1] - b[1]) < 0.0001 && Math.abs(a[0] - b[0]) >= label.width + 16) {
+        const [above, below] = parallelOnLowSide(a, b, 0) ? [1, 0] : [0, 1];
+        for (const fraction of fractions) {
+          const x = a[0] + (b[0] - a[0]) * fraction;
+          if (Math.min(Math.abs(x - a[0]), Math.abs(x - b[0])) < label.width / 2 + 6) continue;
+          ranked.push([above, x, a[1] - 10], [below, x, a[1] + 20], [2, x, a[1] + 3], [3, x, a[1] - 18], [3, x, a[1] + 28]);
+        }
+      } else if (Math.abs(a[0] - b[0]) < 0.0001 && Math.abs(a[1] - b[1]) >= label.height + 16) {
+        const leftFirst = !parallelOnLowSide(a, b, 1);
+        for (const fraction of fractions) {
+          const y = a[1] + (b[1] - a[1]) * fraction;
+          if (Math.min(Math.abs(y - a[1]), Math.abs(y - b[1])) < label.height / 2 + 6) continue;
+          ranked.push([2, a[0], y + 3]);
+          [6, 14, 22, 30, 38, 46, 54].forEach((offset, step) => {
+            const tier = step === 0 ? 0 : step === 1 ? 1 : 2 + step;
+            const left = [tier + (leftFirst ? 0 : 0.5), a[0] - label.width / 2 - offset, y + 3];
+            const right = [tier + (leftFirst ? 0.5 : 0), a[0] + label.width / 2 + offset, y + 3];
+            ranked.push(left, right);
+          });
+        }
+      }
+    }
+    return ranked.map((entry, order) => [...entry, order])
+      .sort((left, right) => left[0] - right[0] || left[3] - right[3])
+      .map(([, lx, ly]) => [lx, ly]);
+  };
+
+  for (const [index, label] of placed.entries()) {
+    const relation = label.relation;
+    if (['labelAt', 'labelDx', 'labelDy', 'labelSegment'].some(key => relation[key] !== undefined)) continue;
+    // Match actual defect thresholds before searching; a valid placement is
+    // not a reason to restyle the diagram. New placements leave extra space.
+    // The grid ranking already starts from the preferred position, so it
+    // also re-ranks labels whose default spot is merely valid.
+    if (!gridSweep && inside(label) && !components.some(component => rectsOverlap(label, component, -2))
+        && !titles.some(title => rectsOverlap(label, title))
+        && !overlapsLabel(label, index) && !masksRoute(label)) continue;
+    if (gridSweep) {
+      // Callers measure the plate one pixel higher than rectAt; test with a
+      // pixel of slack so the chosen position also passes their clearance.
+      const replacement = gridCandidates(label).map(([lx, ly]) => rectAt(label, lx, ly))
+        .find(rect => clear({ ...rect, x: rect.x - 1, y: rect.y - 1, width: rect.width + 2, height: rect.height + 2 }, index));
+      if (replacement) {
+        placed[index] = replacement;
+        continue;
+      }
+    }
+    for (const segment of segments.filter(segment => segment.relationIndex === label.relationIndex)) {
+      const [a, b] = [segment.start, segment.end];
+      let candidates = [];
+      if (Math.abs(a[1] - b[1]) < 0.0001 && Math.abs(a[0] - b[0]) >= label.width + 16) {
+        candidates = [0.5, 0.25, 0.75, 0.125, 0.875].flatMap(fraction => {
+          const x = a[0] + (b[0] - a[0]) * fraction;
+          if (Math.min(Math.abs(x - a[0]), Math.abs(x - b[0])) < 8) return [];
+          return [
+            [x, a[1] - 10],
+            [x, a[1] + 20],
+            [x, a[1] - 18],
+            [x, a[1] + 28],
+          ];
+        });
+      } else if (Math.abs(a[0] - b[0]) < 0.0001 && Math.abs(a[1] - b[1]) >= label.height + 16) {
+        candidates = [0.5, 0.25, 0.75, 0.125, 0.875].flatMap(fraction => {
+          const y = a[1] + (b[1] - a[1]) * fraction;
+          if (Math.min(Math.abs(y - a[1]), Math.abs(y - b[1])) < 8) return [];
+          return [
+            [a[0] - label.width / 2 - 6, y + 3],
+            [a[0] + label.width / 2 + 6, y + 3],
+            [a[0] - label.width / 2 - 14, y + 3],
+            [a[0] + label.width / 2 + 14, y + 3],
+          ];
+        });
+      }
+      const replacement = candidates.map(([lx, ly]) => rectAt(label, lx, ly))
+        .find(rect => clear(rect, index));
+      if (replacement) {
+        placed[index] = replacement;
+        break;
+      }
+    }
+    if (placed[index] !== label || !fallbackRing) continue;
+
+    // Dense but valid topologies can leave every point directly beside the
+    // relationship occupied by another route. Search a small deterministic
+    // ring around the current anchor and the relationship's segment centres.
+    // A collision-free island above a node is not a readable edge label.
+    // Architecture opts into keeping the mask within two label heights of
+    // its own route; shared callers retain their existing policy. If no nearby
+    // slot fits, retain the collision so validation can request more space.
+    const ownSegments = segments.filter(segment => segment.relationIndex === label.relationIndex);
+    const baseAnchors = [
+      [label.lx, label.ly],
+      ...ownSegments.map(segment => [
+        (segment.start[0] + segment.end[0]) / 2,
+        (segment.start[1] + segment.end[1]) / 2,
+      ]),
+    ];
+    const horizontalStep = label.width / 2 + 12;
+    const ringOffsets = [
+      [0, -28], [0, 38],
+      [-horizontalStep, -28], [horizontalStep, -28],
+      [-horizontalStep, 38], [horizontalStep, 38],
+      [-(label.width + 20), -52], [label.width + 20, -52],
+      [-(label.width + 20), 62], [label.width + 20, 62],
+      [-(label.width + 20), -76], [label.width + 20, -76],
+      [-(label.width + 20), 86], [label.width + 20, 86],
+    ];
+    const fallback = baseAnchors.flatMap(([baseX, baseY]) => (
+      ringOffsets.map(([dx, dy]) => rectAt(label, baseX + dx, baseY + dy))
+    )).find(rect => clear(rect, index) && (!keepFallbackNearRoute || ownSegments.some(segment => (
+      segmentRectClearanceWithin(segment, rect, label.height * 2) <= label.height * 2
+    ))));
+    if (fallback) placed[index] = fallback;
+  }
+  return placed;
+}
+
+// The rect a single unpinned label would occupy given only its own route and
+// the nodes: what the planner reserves before the remaining routes are laid.
+// Only a placement beside the route itself is worth reserving; a label that
+// would already need the fallback ring is left to the final placement pass.
+export function reservedLabelRect({
+  label, points, routes = [], labels = [], components, viewBox = [Infinity, Infinity], placementBottom = Infinity,
+}) {
+  const [rect] = placeAutomaticLabels({
+    labels: [{ ...label, relationIndex: -1 }, ...labels.map(other => ({ ...other, relationIndex: -2 }))],
+    routes: [{ relationIndex: -1, points }, ...routes],
+    components,
+    titles: [],
+    viewBox,
+    placementBottom,
+    fallbackRing: false,
+  });
+  return components.some(component => rectsOverlap(rect, component, -2)) ? null : rect;
+}