arch-map

Arch-Map Protocol

Maps an artifact onto architecture elements from an arch_items catalog. Fully automatic — does not ask the user, does not block the task.

Step 1 — Find platform DB

DB_PATH=$(find {projects_root} -name "platform.sqlite" -path "*/data/platform/*" | head -1)

Not found or empty:

Arch-map: platform.sqlite not found — arch_ref = null

End protocol. Continue task execution.

Step 2 — Load arch_items

sqlite3 "$DB_PATH" \
  "SELECT item_type, slug, title, description, url, path
   FROM arch_items WHERE path != '' OR title != '';"

Step 3 — Determine mode and find matches

file-mode (fast-track / pipeline)

Source: files_to_modify from plan-first.

For each file: check whether arch_item.path is a substring of the file path or the file path starts with arch_item.path.

feature-mode (brief / spec)

Source: full text of the artifact.

For each arch_item check: does arch_item.slug, arch_item.title, or arch_item.url appear in the artifact text (case-insensitive).

Collect unique matches. Format: {item_type}/{slug}.

Step 4 — Show result

Matches found:

Arch-map (file-mode):
  api/billing      → api/billing/    [OK]
  page_front/auth  → src/pages/auth/ [WIP]
arch_ref: api/billing,page_front/auth

No matches:

Arch-map: no matches found — arch_ref = null

Step 5 — Add arch_ref column (if missing)

sqlite3 {routing_db} \
  "ALTER TABLE artifacts ADD COLUMN arch_ref TEXT;" 2>/dev/null || true

Step 5.5 — Save result to log

Write {log_dir}/arch-map.md with task, date, mode, full result output, arch_ref value. If {log_dir} unknown — skip without error.

Step 6 — Merge and write arch_ref

arch_ref not null:

1. Read current: SELECT arch_ref FROM artifacts WHERE id = '{artifact_id}';
2. Combine current + new → split by comma, deduplicate, join back
3. Write: UPDATE artifacts SET arch_ref = '{merged}', updated_at = '{date}' WHERE id = '{artifact_id}';