@tyroneross/build-loop 0.30.3

package/skills/spec-writing/scripts/check_checklist.py

@@ -0,0 +1,478 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""
+check_checklist.py — deterministic spec-writing checklist verifier.
+
+Reads a plan markdown file, locates the <!-- checklist --> HTML comment block,
+and checks whether each required item is answered (not blank, not
+the literal placeholder text, and not omitted entirely).
+
+Exit codes:
+    0 — all required items answered (Items 15 and 17 are conditional on UI files in scope)
+    1 — one or more items missing or unanswered
+    2 — verifier error (file not found, parse failure)
+
+Usage:
+    python3 check_checklist.py --plan docs/plans/my-feature.md [--json] [--quiet]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+ITEMS: list[tuple[str, str]] = [
+    ("item_1_auth_guard",              "Item 1 — Auth guard"),
+    ("item_2_external_apis",           "Item 2 — External APIs"),
+    ("item_3_rate_limit",              "Item 3 — Rate-limit criterion"),
+    ("item_4_discoverability",         "Item 4 — Discoverability"),
+    ("item_5_server_client_boundary",  "Item 5 — Server/client boundary"),
+    ("item_6_concurrency",             "Item 6 — Concurrency"),
+    ("item_7_observability",           "Item 7 — Observability"),
+    ("item_8_input_validation",        "Item 8 — Input validation"),
+    ("item_9_stable_id_traceability",  "Item 9 — Stable ID traceability"),
+    ("item_10_json_spec_object",       "Item 10 — JSON spec object"),
+    ("item_11_blocking_and_novel_question_gate", "Item 11 — Blocking-and-novel question gate"),
+    ("item_12_low_reversibility_adrs", "Item 12 — Low-reversibility ADRs"),
+    ("item_13_analytical_lens",        "Item 13 — Analytical lens"),
+    ("item_14_handoff_document",       "Item 14 — Handoff document"),
+    ("item_15_synthesis_dimensions",   "Item 15 — Synthesis dimensions"),
+    ("item_16_risk_reason",            "Item 16 — Risk reason"),
+    ("item_17_ui_io_contract",         "Item 17 — UI input/output contract"),
+]
+
+# Values that count as "not answered" — case-insensitive, stripped
+PLACEHOLDER_PATTERNS: list[re.Pattern] = [
+    re.compile(r"^<answer>$"),
+    re.compile(r"^\.\.\.$"),
+    re.compile(r"^$"),
+    re.compile(r"^tbd$", re.IGNORECASE),
+    re.compile(r"^todo$", re.IGNORECASE),
+    re.compile(r"^none$", re.IGNORECASE),
+]
+
+CHECKLIST_RE = re.compile(
+    r"<!--\s*checklist\s*(.*?)\s*-->",
+    re.DOTALL | re.IGNORECASE,
+)
+
+ITEM_LINE_RE = re.compile(
+    r"^(Item\s*\d+\s*[—\-–]\s*[^:]+)\s*:\s*(.*)$",
+    re.IGNORECASE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Parsing
+# ---------------------------------------------------------------------------
+
+def extract_checklist_block(text: str) -> str | None:
+    """Return the inner text of the first <!-- checklist ... --> block, or None."""
+    m = CHECKLIST_RE.search(text)
+    return m.group(1).strip() if m else None
+
+
+def parse_checklist_block(block: str) -> dict[str, str]:
+    """
+    Parse `Item N — Label: answer` lines from the checklist block.
+    Returns a dict mapping the item label prefix (lowercased, spaces→underscores)
+    to the answer string.
+    """
+    parsed: dict[str, str] = {}
+    for line in block.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        m = ITEM_LINE_RE.match(line)
+        if m:
+            key = _normalize_label(m.group(1))
+            parsed[key] = m.group(2).strip()
+    return parsed
+
+
+def _normalize_label(label: str) -> str:
+    """'Item 1 — Auth guard' → 'item_1_auth_guard'"""
+    s = label.lower()
+    s = re.sub(r"[—\-–]+", " ", s)
+    s = re.sub(r"[^a-z0-9\s]", "", s)
+    s = re.sub(r"\s+", "_", s.strip())
+    return s
+
+
+def is_answered(value: str) -> bool:
+    v = value.strip()
+    return not any(p.match(v) for p in PLACEHOLDER_PATTERNS)
+
+
+# ---------------------------------------------------------------------------
+# Structural validators for items 9-14
+# ---------------------------------------------------------------------------
+
+# ID patterns: U-NN, F-NN, D-NN, S-NN, T-NN, A-NN
+_ID_RE = re.compile(r"\b[UFDSTA]-\d+\b")
+_P0_LINE_RE = re.compile(r"\[P0\]", re.IGNORECASE)
+_T_ID_RE = re.compile(r"\bT-\d+\b")
+_A_ID_RE = re.compile(r"\bA-\d+\b")
+_JSON_SPEC_SECTION_RE = re.compile(r"^##\s+Spec Object.*\(JSON\)", re.IGNORECASE | re.MULTILINE)
+_OPEN_Q_SECTION_RE = re.compile(r"^##\s+Open Questions", re.IGNORECASE | re.MULTILINE)
+_BLOCKING_TEST_RE = re.compile(r"blocking-test:\s*T-\d+", re.IGNORECASE)
+_ADR_HEADING_RE = re.compile(r"^##\s+ADR-\d+", re.IGNORECASE | re.MULTILINE)
+_LOW_REV_RE = re.compile(
+    r"low-reversib|db choice|auth provider|api contract|public schema",
+    re.IGNORECASE,
+)
+_LENS_LINE_RE = re.compile(r"analytical lens\s*:", re.IGNORECASE)
+
+# Items 15 and 17 — UI-only checks.
+_UI_FILE_RE = re.compile(
+    r"""
+    (
+      \b[\w/.\-]+\.(?:tsx|jsx|vue|svelte)\b
+      |(?:^|[\s`(/])components/[\w/.\-]+
+      |(?:^|[\s`(/])(?:app|pages)/(?!(?:api|_app|_document)\b)[\w/.\-]*(?:page|layout)\.(?:ts|tsx|js|jsx)\b
+      |(?:^|[\s`(/])Views/[\w/.\-]+\.swift\b
+      |\b[\w/.\-]*(?:View|Screen|Page)\.swift\b
+    )
+    """,
+    re.IGNORECASE | re.VERBOSE,
+)
+_SYNTHESIS_BLOCK_RE = re.compile(
+    r"synthesis_dimensions\s*:\s*\n((?:[ \t]+[\w_]+\s*:.*\n?)+)", re.IGNORECASE)
+_REQUIRED_SYNTHESIS_KEYS = ("placement", "cta_tier", "copy_tone",
+                            "visual_weight", "empty_state")
+_UI_IO_SECTION_RE = re.compile(
+    r"^##\s+UI\s+Input/Output\s+Contract\b", re.IGNORECASE | re.MULTILINE)
+_UI_IO_REQUIRED_TERMS = (
+    "surface", "input", "output", "taxonomy", "operation", "component",
+    "state", "modality", "validation", "traceability",
+)
+
+
+def check_item_15_synthesis_dimensions(plan_text: str) -> tuple[str, str | None]:
+    """OK if no UI in scope; else require synthesis_dimensions block w/ all keys."""
+    if not _UI_FILE_RE.search(plan_text):
+        return ("OK", None)
+    m = _SYNTHESIS_BLOCK_RE.search(plan_text)
+    if not m:
+        return ("FAIL", "UI files detected but no `synthesis_dimensions:` block. "
+                "Required keys: " + ", ".join(_REQUIRED_SYNTHESIS_KEYS) + ".")
+    body = m.group(1)
+    missing = [k for k in _REQUIRED_SYNTHESIS_KEYS
+               if not re.search(rf"^\s+{re.escape(k)}\s*:", body, re.MULTILINE)]
+    if missing:
+        return ("FAIL", "synthesis_dimensions missing key(s): " + ", ".join(missing))
+    return ("OK", None)
+
+
+def check_item_17_ui_io_contract(plan_text: str) -> tuple[str, str | None]:
+    """OK if no UI in scope; else require a UI Input/Output Contract section."""
+    if not _UI_FILE_RE.search(plan_text):
+        return ("OK", None)
+
+    m = _UI_IO_SECTION_RE.search(plan_text)
+    if not m:
+        return ("FAIL", "UI files detected but no `## UI Input/Output Contract` section found.")
+
+    section_start = m.end()
+    next_heading = re.search(r"^##\s+", plan_text[section_start:], re.MULTILINE)
+    section = (
+        plan_text[section_start: section_start + next_heading.start()]
+        if next_heading else plan_text[section_start:]
+    )
+    lower = section.lower()
+    missing = [term for term in _UI_IO_REQUIRED_TERMS if term not in lower]
+    if missing:
+        return ("FAIL", "UI Input/Output Contract missing term(s): " + ", ".join(missing))
+    return ("OK", None)
+
+
+def _structural_findings(text: str, plan_path: Path) -> list[dict]:
+    """
+    Run structural checks for higher-order checklist items against the full plan text.
+    Returns a list of finding dicts (same shape as checklist findings).
+    Each finding has item_id, label, status ('ok'|'warn'|'fail'), and message.
+    These supplement — they do not replace — the checklist block checks.
+    """
+    findings = []
+
+    # Item 9: P0 lines must have at least one T- reference
+    p0_lines = [ln for ln in text.splitlines() if _P0_LINE_RE.search(ln)]
+    if p0_lines:
+        p0_without_test = [ln for ln in p0_lines if not _T_ID_RE.search(ln)]
+        if p0_without_test:
+            findings.append({
+                "item_id": "item_9_stable_id_traceability",
+                "label": "Item 9 — Stable ID traceability",
+                "status": "warn",
+                "message": (
+                    f"{len(p0_without_test)} [P0] line(s) found without a linked T-NN test ID. "
+                    "Each P0 must trace to at least one acceptance test."
+                ),
+            })
+        else:
+            # Also verify at least one full trace chain appears (U-, F-, T-)
+            has_chain = (
+                bool(_ID_RE.search(text))
+                and bool(re.search(r"\bU-\d+\b", text))
+                and bool(re.search(r"\bF-\d+\b", text))
+            )
+            if not has_chain:
+                findings.append({
+                    "item_id": "item_9_stable_id_traceability",
+                    "label": "Item 9 — Stable ID traceability",
+                    "status": "warn",
+                    "message": (
+                        "P0 lines have T- links but no full U-NN → F-NN → T-NN chain found. "
+                        "Add stable IDs threading from user need through feature to test."
+                    ),
+                })
+
+    # Item 10: ## Spec Object (JSON) section must exist
+    if not _JSON_SPEC_SECTION_RE.search(text):
+        findings.append({
+            "item_id": "item_10_json_spec_object",
+            "label": "Item 10 — JSON spec object",
+            "status": "warn",
+            "message": (
+                "No '## Spec Object (JSON)' section found. "
+                "Emit a structured JSON block before rendering markdown."
+            ),
+        })
+
+    # Item 11: Open Questions entries must carry blocking-test: annotation
+    oq_match = _OPEN_Q_SECTION_RE.search(text)
+    if oq_match:
+        # Extract the Open Questions section (up to the next ## heading)
+        oq_start = oq_match.end()
+        next_heading = re.search(r"^##\s+", text[oq_start:], re.MULTILINE)
+        oq_body = text[oq_start: oq_start + next_heading.start()] if next_heading else text[oq_start:]
+        # Count question lines (non-empty, non-heading lines)
+        q_lines = [ln.strip() for ln in oq_body.splitlines()
+                   if ln.strip() and not ln.strip().startswith("#")]
+        missing_annotation = [ln for ln in q_lines if not _BLOCKING_TEST_RE.search(ln)]
+        if missing_annotation:
+            findings.append({
+                "item_id": "item_11_blocking_and_novel_question_gate",
+                "label": "Item 11 — Blocking-and-novel question gate",
+                "status": "warn",
+                "message": (
+                    f"{len(missing_annotation)} Open Question line(s) lack a 'blocking-test: T-NN' "
+                    "annotation. Convert non-blocking questions to [ASSUMED: ...] entries."
+                ),
+            })
+
+    # Item 12: Low-reversibility decision mentions must have ADR link
+    low_rev_lines = [ln for ln in text.splitlines() if _LOW_REV_RE.search(ln)]
+    adr_headings_exist = bool(_ADR_HEADING_RE.search(text))
+    if low_rev_lines and not adr_headings_exist:
+        findings.append({
+            "item_id": "item_12_low_reversibility_adrs",
+            "label": "Item 12 — Low-reversibility ADRs",
+            "status": "warn",
+            "message": (
+                f"{len(low_rev_lines)} low-reversibility decision mention(s) found but no "
+                "'## ADR-NN:' section detected. Each such decision needs an ADR record."
+            ),
+        })
+
+    # Item 13: Analytical lens line must appear in the plan body (outside the checklist block)
+    body_text = CHECKLIST_RE.sub("", text)  # strip the <!-- checklist --> block
+    if not _LENS_LINE_RE.search(body_text):
+        findings.append({
+            "item_id": "item_13_analytical_lens",
+            "label": "Item 13 — Analytical lens",
+            "status": "warn",
+            "message": (
+                "No 'Analytical lens:' line found in the plan body. "
+                "Name the lens (JTBD, QFD, TRIZ, Pugh/AHP, DSM, etc.) in Locked Decisions."
+            ),
+        })
+
+    # Item 14: Sibling .handoff.md must exist
+    slug = plan_path.stem  # e.g. "my-feature" from "my-feature.md"
+    handoff_path = plan_path.parent / f"{slug}.handoff.md"
+    if not handoff_path.exists():
+        findings.append({
+            "item_id": "item_14_handoff_document",
+            "label": "Item 14 — Handoff document",
+            "status": "warn",
+            "message": (
+                f"Sibling handoff file '{handoff_path.name}' not found. "
+                "Generate docs/plans/<slug>.handoff.md alongside the plan."
+            ),
+        })
+
+    # Item 15: Synthesis dimensions block required when UI is in scope
+    status_15, msg_15 = check_item_15_synthesis_dimensions(text)
+    if status_15 == "FAIL":
+        findings.append({
+            "item_id": "item_15_synthesis_dimensions",
+            "label": "Item 15 — Synthesis dimensions",
+            "status": "fail",
+            "message": msg_15,
+        })
+
+    # Item 17: UI Input/Output Contract required when UI is in scope
+    status_17, msg_17 = check_item_17_ui_io_contract(text)
+    if status_17 == "FAIL":
+        findings.append({
+            "item_id": "item_17_ui_io_contract",
+            "label": "Item 17 — UI input/output contract",
+            "status": "fail",
+            "message": msg_17,
+        })
+
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Main verification
+# ---------------------------------------------------------------------------
+
+def verify(plan_path: Path) -> dict:
+    """
+    Returns a result dict:
+    {
+        "plan": str,
+        "checklist_found": bool,
+        "findings": [{"item_id": str, "label": str, "answer": str|None, "status": "ok"|"missing"|"unanswered"}],
+        "structural_warnings": [{"item_id": str, "label": str, "status": "warn", "message": str}],
+        "missing_count": int,
+        "structural_warning_count": int,
+        "exit_code": int  # 0=clean, 1=failures, 2=error
+    }
+    """
+    try:
+        text = plan_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return {
+            "plan": str(plan_path),
+            "checklist_found": False,
+            "findings": [],
+            "structural_warnings": [],
+            "missing_count": len(ITEMS),
+            "structural_warning_count": 0,
+            "exit_code": 2,
+            "error": str(exc),
+        }
+
+    block = extract_checklist_block(text)
+    if block is None:
+        findings = [
+            {
+                "item_id": item_id,
+                "label": label,
+                "answer": None,
+                "status": "missing",
+                "message": "No <!-- checklist --> block found in plan file.",
+            }
+            for item_id, label in ITEMS
+        ]
+        return {
+            "plan": str(plan_path),
+            "checklist_found": False,
+            "findings": findings,
+            "structural_warnings": [],
+            "missing_count": len(ITEMS),
+            "structural_warning_count": 0,
+            "exit_code": 1,
+        }
+
+    parsed = parse_checklist_block(block)
+    # Items 15 and 17 are conditional: only required when UI files are in scope.
+    ui_in_scope = bool(_UI_FILE_RE.search(text))
+
+    findings = []
+    missing = 0
+    for item_id, label in ITEMS:
+        normalized = _normalize_label(label)
+        # Item 15/17 optional when no UI in scope; Item 16 always optional (only required
+        # when author has identified a high-consequence boundary — absent is valid).
+        is_optional = (
+            (item_id == "item_15_synthesis_dimensions" and not ui_in_scope)
+            or item_id == "item_16_risk_reason"
+            or (item_id == "item_17_ui_io_contract" and not ui_in_scope)
+        )
+        if normalized not in parsed:
+            if is_optional:
+                findings.append({"item_id": item_id, "label": label, "answer": None,
+                                 "status": "ok", "message": "N/A: no UI in scope."})
+                continue
+            findings.append({"item_id": item_id, "label": label, "answer": None,
+                             "status": "missing",
+                             "message": f"Item not found. Expected '{label}:'"})
+            missing += 1
+        elif not is_answered(parsed[normalized]):
+            if is_optional:
+                findings.append({"item_id": item_id, "label": label,
+                                 "answer": parsed[normalized], "status": "ok",
+                                 "message": "N/A: no UI in scope."})
+                continue
+            findings.append({"item_id": item_id, "label": label,
+                             "answer": parsed[normalized], "status": "unanswered",
+                             "message": "Placeholder or empty. Provide answer or 'N/A: <reason>'."})
+            missing += 1
+        else:
+            findings.append({"item_id": item_id, "label": label,
+                             "answer": parsed[normalized], "status": "ok"})
+
+    structural_warnings = _structural_findings(text, plan_path)
+    structural_fail_count = sum(1 for w in structural_warnings if w.get("status") == "fail")
+    return {
+        "plan": str(plan_path), "checklist_found": True, "findings": findings,
+        "structural_warnings": structural_warnings, "missing_count": missing,
+        "structural_warning_count": len(structural_warnings),
+        "structural_fail_count": structural_fail_count,
+        "exit_code": 0 if (missing == 0 and structural_fail_count == 0) else 1,
+    }
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Verify spec-writing checklist in a plan markdown file."
+    )
+    parser.add_argument("--plan", required=True, help="Path to the plan markdown file.")
+    parser.add_argument("--json", action="store_true", dest="as_json",
+                        help="Emit JSON output.")
+    parser.add_argument("--quiet", action="store_true",
+                        help="Suppress human-readable summary (use with --json).")
+    args = parser.parse_args()
+
+    plan_path = Path(args.plan)
+    result = verify(plan_path)
+
+    if args.as_json:
+        print(json.dumps(result, indent=2))
+
+    if not args.quiet:
+        status = "CLEAN" if result["exit_code"] == 0 else "INCOMPLETE"
+        warn_count = result.get("structural_warning_count", 0)
+        print(
+            f"check_checklist — {status} "
+            f"({result['missing_count']} items missing/unanswered, "
+            f"{warn_count} structural warnings)"
+        )
+        for f in result["findings"]:
+            if f["status"] != "ok":
+                print(f"  [{f['status'].upper()}] {f['label']}: {f.get('message', '')}")
+        for w in result.get("structural_warnings", []):
+            tag = w.get("status", "warn").upper()
+            print(f"  [{tag}] {w['label']}: {w.get('message', '')}")
+
+    return result["exit_code"]
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/sync-skills/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: build-loop:sync-skills
+description: Use when the user asks to "check skill drift", "sync skills", or "update architecture skills", or when Phase 1 Assess detects stale source_hash values. Walks skills/architecture/ and skills/debugging/, recomputes source_hash, reports drift. Read-only.
+version: 0.1.0
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Sync-Skills — Drift Detection for Native Copies
+
+Build-loop's `skills/architecture/` and `skills/debugging/` skills are copied from canonical upstream repos (NavGator, claude-code-debugger). Each carries a `source:` path and `source_hash:` SHA-256 in its frontmatter. This skill recomputes the hash from the canonical source file and reports any drift.
+
+**Read-only.** Never auto-updates a skill — surfaces a list of skills that need refresh and a one-line refresh command.
+
+## When to Activate
+
+- User asks "check skill drift", "sync skills", "are native skills stale"
+- After updating NavGator or claude-code-debugger locally and you want to know which build-loop skills inherit the change
+- Periodic maintenance (run quarterly, or before any release that touches the architecture/debugging surfaces)
+
+## Workflow
+
+Run the drift-check script:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/sync_skills.py
+```
+
+Or inline (no script dependency):
+
+```bash
+python3 - <<'PY'
+import hashlib, os, pathlib, re, sys
+
+ROOT = pathlib.Path(os.environ.get("CLAUDE_PLUGIN_ROOT") or pathlib.Path(__file__).resolve().parents[2])
+HOME = pathlib.Path.home()
+
+def read_frontmatter(path):
+    text = path.read_text()
+    m = re.match(r'^---\n(.*?)\n---\n', text, re.DOTALL)
+    if not m:
+        return {}
+    fm = {}
+    for line in m.group(1).splitlines():
+        if ':' in line:
+            k, v = line.split(':', 1)
+            fm[k.strip()] = v.strip().strip('"').strip("'")
+    return fm
+
+def find_canonical(rel_path):
+    # Try common parent dirs
+    for parent in [HOME / "dev" / "git-folder", ROOT.parent, pathlib.Path.cwd()]:
+        candidate = parent / rel_path
+        if candidate.exists():
+            return candidate
+    return None
+
+drift = []
+checked = 0
+for tree in ["skills/architecture", "skills/debugging"]:
+    for skill_md in (ROOT / tree).rglob("SKILL.md"):
+        fm = read_frontmatter(skill_md)
+        src = fm.get("source")
+        expected_hash = fm.get("source_hash")
+        if not src or not expected_hash:
+            continue
+        canonical = find_canonical(src)
+        rel = skill_md.relative_to(ROOT)
+        checked += 1
+        if not canonical:
+            drift.append((str(rel), "MISSING", "canonical source not found: " + src))
+            continue
+        actual = hashlib.sha256(canonical.read_bytes()).hexdigest()
+        if actual != expected_hash:
+            drift.append((str(rel), "DRIFT", f"expected {expected_hash[:12]} got {actual[:12]}"))
+
+print(f"Checked: {checked} skills")
+if not drift:
+    print("Status: clean — no drift")
+    sys.exit(0)
+
+print(f"Status: {len(drift)} drift(s)")
+for rel, kind, detail in drift:
+    print(f"  [{kind}] {rel}")
+    print(f"          {detail}")
+print()
+print("Refresh: rerun build-loop:sync-skills with --refresh after reviewing the canonical diff,")
+print("or invoke the orchestrator to re-import the affected skill(s).")
+sys.exit(1 if drift else 0)
+PY
+```
+
+## Output
+
+- **Clean**: `Checked: 10 skills. Status: clean — no drift.`
+- **Drift detected**: list of `<skill path> | DRIFT | expected <hash-prefix> got <hash-prefix>` plus one-line refresh hint
+- **Missing canonical**: list of `<skill path> | MISSING | canonical source not found: <path>` — means upstream repo moved or was deleted
+
+## What This Skill Does NOT Do
+
+- Does not auto-update SKILL.md files (refresh is a deliberate, reviewed action)
+- Does not modify the canonical source repos
+- Does not re-import — the user (or build-orchestrator on user request) re-runs the import flow
+
+## How to Refresh a Drifted Skill
+
+1. Read the canonical source file at the path in `source:`
+2. Diff against the local SKILL.md (skipping the rewritten frontmatter and any build-loop-specific sibling-skill references)
+3. Decide: pull the upstream change, keep local fork, or escalate to user
+4. If pulling: re-author the local SKILL.md preserving the build-loop-specific framing (skill name, sibling references), recompute `source_hash`, update frontmatter
+5. Re-run `build-loop:sync-skills` to confirm drift cleared
+
+## Locations Walked
+
+- `skills/architecture/scan/SKILL.md`
+- `skills/architecture/impact/SKILL.md`
+- `skills/architecture/trace/SKILL.md`
+- `skills/architecture/rules/SKILL.md`
+- `skills/architecture/dead/SKILL.md`
+- `skills/architecture/review/SKILL.md`
+- `skills/debugging/memory/SKILL.md`
+- `skills/debugging/store/SKILL.md`
+- `skills/debugging/assess/SKILL.md`
+- `skills/debugging/debug-loop/SKILL.md`
+
+## Sibling Skills
+
+- All skills under `build-loop:architecture-*` — drift-checked by this skill
+- All skills under `build-loop:debugging-*` — drift-checked by this skill
+
+*Native to build-loop. Not copied from any upstream — this is the drift-detector itself.*

package/skills/telemetry/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: telemetry
+description: Use when adding observability/telemetry to an app, instrumenting traces/metrics/logs, wiring LLM/agent tracing, choosing a monitoring vendor, or auditing an app for missing telemetry. Triggers — "add telemetry", "add observability", "instrument this", "tracing", "OpenTelemetry/OTel", "LLM observability", "LangChain tracing", "Phoenix/Langfuse/LangSmith", "Crashlytics/Sentry/mobile telemetry", "why is this slow in prod", "no visibility into". OpenTelemetry-first, vendor-neutral.
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Telemetry — OpenTelemetry-first, vendor-neutral
+
+**The rule:** default to **OpenTelemetry (OTel)**. Instrument with OTel SDKs + **GenAI semantic conventions**; export OTLP to whatever backend fits. Never lock telemetry to a single proprietary vendor, and **never roll your own tracing schema** — OTel conventions exist. This codifies the user's already-decided stack (`prefer-opentelemetry`); it is a default, not dogma — document an exception when a closed tool genuinely wins.
+
+Canonical working exemplar in-tree: **`sample-observability-app/src/observability.py`** (OTLP/HTTP → Phoenix, env-gated `SAMPLE_OBSERVE=1`, fails silent). Copy this pattern; don't reinvent it.
+
+## Decision tree — pick the stack by app type
+
+| App type | Instrument with | Dev backend | Prod backend | Error tracking |
+|---|---|---|---|---|
+| **LLM / agent** (LangChain, LangGraph, raw SDK) | `openinference-instrumentation-langchain` **or** `opentelemetry-instrumentation-langchain` (OpenLLMetry) + OTel SDK | **Arize Phoenix** (Apache-2.0, OTLP-native, local eval UI) | **Langfuse** (self-host, OTLP `/api/public/otel`, evals + replay) | Sentry |
+| **Web / server** (Node, Python) | `@opentelemetry/sdk-node` (JS SDK 2.0, stable) / `opentelemetry-sdk` (Python) + auto-instrumentations | OTel Collector → any | Grafana/SigNoz/Honeycomb/Datadog via OTLP | **Sentry** (the record for deployed web apps) |
+| **Mobile / iOS** (SwiftUI) | **Embrace Apple SDK** (Apache-2.0, built on `opentelemetry-swift`; adds crash/ANR/session/UI that bare OTel-Swift lacks) | — | any OTLP backend (Grafana/SigNoz/Honeycomb) | Embrace or Sentry-cocoa (MIT) |
+
+**LLM tracing — three paths, in preference order:** (A) **OpenLLMetry** `opentelemetry-instrumentation-langchain` — `LangchainInstrumentor().instrument()`, vendor-neutral OTLP; (B) **OpenInference** `openinference-instrumentation-langchain` — same monkey-patch model, tight Phoenix integration; (C) **LangSmith** — opt-in only (proprietary backend; has OTLP export but canonical storage stays LangSmith). LangChain does **not** emit OTel natively as of 2026, so an instrumentation lib is required. LangSmith stays behind a flag — "no paid posture."
+
+**Mobile — the Firebase tradeoff (stated plainly):** Firebase's iOS SDK is Apache-2.0, but **Crashlytics/Performance emit no OTLP** — data is trapped in the Firebase console (or BigQuery export). For OTel portability Firebase Performance is a dead end; Crashlytics is fine for triage only. Prefer Embrace (OTel-compatible) when portability/reliability matter. Note: CocoaPods support for firebase-ios-sdk ends Oct 2026 (SPM only).
+
+## Minimal wire-up (Python LLM app)
+
+```python
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.instrumentation.langchain import LangchainInstrumentor
+
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(
+    OTLPSpanExporter(endpoint="http://otel-collector:4317")))  # swap endpoint = swap backend
+LangchainInstrumentor().instrument(tracer_provider=provider)
+```
+
+Use GenAI semconv attributes (`gen_ai.system`, `gen_ai.request.model`, `gen_ai.usage.input_tokens`) so the data is backend-agnostic. Gate observability behind an env flag, default-off on cheap tiers (OTel + batch processor adds ~10–50 ms/call). Probe the backend at startup and **warn without blocking** if it's down (fail-silent, like the sample observability exemplar).
+
+## Status (2026, cite before relying — these move)
+
+- OTel **GenAI client spans stable** (early 2026); agent/framework spans experimental-but-stable-in-practice. JS SDK 2.0 stable; Python SDK stable.
+- Phoenix, Langfuse, OpenLLMetry, OpenInference all OTLP-compatible and OSS.
+- Embrace Kotlin SDK donated to OTel (CNCF, Mar 2026, KMP — Android-first); Embrace **Apple** SDK stays in Embrace's repo (Apache-2.0) but is built on OTel primitives.
+
+## Instrumentation gaps in this user's repos (audit 2026-05-31)
+
+Already instrumented (reference these): **sample-observability-app** (OTel+Phoenix+OpenInference, full), **sample-reader/sample-rag** (OTel full + Sentry), **sample-secrets-service** (OTel metrics).
+
+**Gaps worth closing first** — LLM/agent apps with zero telemetry:
+1. **sample-research-app** — LangChain + LangGraph, nothing. Drop in the sample observability pattern (~10 lines) for instant span/token visibility.
+2. **sample-strategy-app** — has LangSmith dep but no OTel plumbing; unify with the OTel-first stack.
+3. **sample-agent-app** — LangGraph, no telemetry.
+
+Partial (error-only, no traces): sample-product-app, sample-decision-app, sample-prompt-lab (Sentry only). **sample-voice-ios** — no telemetry; candidate for Embrace Apple SDK.
+
+## When build-loop fires this skill
+
+Phase 1 Assess: if the build touches a server/LLM/mobile app with no telemetry, flag the gap. Phase 2 Plan: if the build adds a new service, LLM call path, or user-facing mobile flow, include an OTel instrumentation step (default-off env flag). Phase 4 Review: a new LLM call path shipped without span coverage is an observability gap to surface, not a blocker.
+
+## Sources
+
+OTel GenAI semconv: opentelemetry.io/docs/specs/semconv/gen-ai/ · JS SDK 2.0: opentelemetry.io/blog/2025/otel-js-sdk-2-0/ · OpenLLMetry: github.com/traceloop/openllmetry · OpenInference: github.com/Arize-ai/openinference · Phoenix: arize.com/docs/phoenix · Langfuse OTel: langfuse.com/integrations/native/opentelemetry · Embrace Apple: github.com/embrace-io/embrace-apple-sdk · opentelemetry-swift: github.com/open-telemetry/opentelemetry-swift · Sentry OTLP: docs.sentry.io/concepts/otlp/ · Firebase: firebase.google.com/docs/crashlytics, /docs/perf-mon.