trae-coding-engine 0.1.0

package/templates/scripts/skill-impact.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# Skill impact report — measures how often each coding-* skill is referenced
+# in commit messages, to inform retire / promote / keep decisions.
+#
+# This is a metric, not a check. Always exits 0. Intended cadence: run every
+# 90 days (or before deciding whether to retire a skill). Output is advisory.
+#
+# Counting model:
+#   refs       = # commits whose message contains the skill name in a window
+#   maint      = # commits that touch .agents/skills/<skill>/* in same window
+#                (this is the "self-maintenance" signal — typically excluded
+#                from the actual usage signal, but shown alongside for context)
+#   age        = days since the first commit that introduced the skill dir
+#
+# Bands (heuristic, tunable below):
+#   age < 30d                      → NEW    (give it time, no judgment)
+#   age ≥ 90d AND refs_365 == 0    → DEAD   (retirement candidate)
+#   age ≥ 30d AND refs_365 == 0    → WATCH  (cooling — re-check in 60d)
+#   refs_365 ≥ 20                  → HOT    (consider promoting to AGENTS.md)
+#   refs_365 ≥ 5                   → WARM
+#   refs_365 ≥ 1                   → COLD
+
+set -euo pipefail
+shopt -s nullglob
+
+cd "$(dirname "$0")/.."
+
+# shellcheck source=scripts/lib/skill-frontmatter.sh
+. scripts/lib/skill-frontmatter.sh
+
+NOW_EPOCH=$(date +%s)
+
+# Tunable thresholds — adjust to your team's commit cadence
+DEAD_AGE_DAYS=90       # below this age, never call something DEAD
+NEW_AGE_DAYS=30        # below this age, classify as NEW (no judgment)
+HOT_REFS_YEAR=20       # at or above this, propose promotion
+WARM_REFS_YEAR=5
+COLD_REFS_YEAR=1
+
+count_refs() {
+    local pattern=$1 since=$2
+    git log --since="$since" --grep="$pattern" --format=%h 2>/dev/null | wc -l | tr -d ' '
+}
+
+count_touches() {
+    local dir=$1 since=$2
+    git log --since="$since" --format=%h -- "$dir" 2>/dev/null | wc -l | tr -d ' '
+}
+
+first_commit_date() {
+    git log --reverse --format=%cs -- "$1" 2>/dev/null | head -1
+}
+
+classify() {
+    local age=$1 refs365=$2
+    if [[ "$age" -lt "$NEW_AGE_DAYS" ]]; then echo "NEW"; return; fi
+    if [[ "$refs365" -eq 0 ]]; then
+        if [[ "$age" -ge "$DEAD_AGE_DAYS" ]]; then echo "DEAD"; else echo "WATCH"; fi
+        return
+    fi
+    if [[ "$refs365" -ge "$HOT_REFS_YEAR" ]];  then echo "HOT";  return; fi
+    if [[ "$refs365" -ge "$WARM_REFS_YEAR" ]]; then echo "WARM"; return; fi
+    echo "COLD"
+}
+
+[[ -d "$SKILLS_ROOT" ]] || { echo "[ERROR] $SKILLS_ROOT not found" >&2; exit 0; }
+
+today=$(date +%Y-%m-%d)
+echo "==> Skill impact report (as of $today)"
+echo ""
+
+new=0; watch=0; dead=0; cold=0; warm=0; hot=0
+
+for dir in "$SKILLS_ROOT"/coding-*; do
+    [[ -d "$dir" ]] || continue
+    name=$(basename "$dir")
+
+    first=$(first_commit_date "$dir")
+    if [[ -n "$first" ]]; then
+        first_epoch=$(parse_date "$first")
+        if [[ -n "$first_epoch" ]]; then
+            age=$(( (NOW_EPOCH - first_epoch) / 86400 ))
+        else
+            age=0
+        fi
+    else
+        age=0
+    fi
+
+    refs30=$(count_refs "$name" "30 days ago")
+    refs90=$(count_refs "$name" "90 days ago")
+    refs365=$(count_refs "$name" "365 days ago")
+    maint=$(count_touches "$dir" "365 days ago")
+
+    cls=$(classify "$age" "$refs365")
+    case "$cls" in
+        NEW)   new=$((new+1)) ;;
+        WATCH) watch=$((watch+1)) ;;
+        DEAD)  dead=$((dead+1)) ;;
+        COLD)  cold=$((cold+1)) ;;
+        WARM)  warm=$((warm+1)) ;;
+        HOT)   hot=$((hot+1)) ;;
+    esac
+
+    note=""
+    case "$cls" in
+        DEAD)  note="  ← retirement candidate" ;;
+        HOT)   note="  ← consider promoting to AGENTS.md" ;;
+        WATCH) note="  ← re-check in 60d" ;;
+    esac
+
+    printf "%-18s age:%4dd   refs:%3d / %3d / %3d  (30d / 90d / 365d)   maint:%3d   %s%s\n" \
+        "$name" "$age" "$refs30" "$refs90" "$refs365" "$maint" "$cls" "$note"
+
+    if [[ "$refs365" -gt 0 ]]; then
+        git log --since="365 days ago" --grep="$name" --format="    %h %s" -3 2>/dev/null \
+            | head -3
+    fi
+done
+
+total=$((new + watch + dead + cold + warm + hot))
+echo ""
+echo "── summary ────────────────────────────────────"
+printf "  %d skill(s) analyzed\n" "$total"
+[[ "$new"   -gt 0 ]] && printf "  %d NEW    (< %dd old, no judgment yet)\n" "$new" "$NEW_AGE_DAYS"
+[[ "$watch" -gt 0 ]] && printf "  %d WATCH  (cooling — re-check in 60d)\n" "$watch"
+[[ "$dead"  -gt 0 ]] && printf "  %d DEAD   (≥ %dd old, 0 refs/year — retire?)\n" "$dead" "$DEAD_AGE_DAYS"
+[[ "$cold"  -gt 0 ]] && printf "  %d COLD   (1-%d refs/year)\n" "$cold" "$((WARM_REFS_YEAR - 1))"
+[[ "$warm"  -gt 0 ]] && printf "  %d WARM   (%d-%d refs/year)\n" "$warm" "$WARM_REFS_YEAR" "$((HOT_REFS_YEAR - 1))"
+[[ "$hot"   -gt 0 ]] && printf "  %d HOT    (≥ %d refs/year — promote to AGENTS.md?)\n" "$hot" "$HOT_REFS_YEAR"
+echo ""
+echo "  Thresholds (tune in scripts/skill-impact.sh):"
+echo "    NEW < ${NEW_AGE_DAYS}d  |  DEAD ≥ ${DEAD_AGE_DAYS}d & 0 refs"
+echo "    HOT ≥ ${HOT_REFS_YEAR}/y  |  WARM ≥ ${WARM_REFS_YEAR}/y  |  COLD ≥ ${COLD_REFS_YEAR}/y"

package/templates/scripts/skill-propose.sh

@@ -0,0 +1,302 @@
+#!/usr/bin/env bash
+# Detects skill gaps and generates draft evolution proposals.
+# Run via: make skill-propose
+# Proposals are created at .agents/skills/proposals/ for human review before MR.
+#
+# Each probe is a self-contained function. Add a new probe by writing a new
+# `probe_<skill>_<concern>` function and calling it at the bottom.
+
+set -euo pipefail
+shopt -s nullglob
+
+PROPOSALS_DIR=".agents/skills/proposals"
+DATE=$(date +%Y-%m-%d)
+GENERATED=0
+
+mkdir -p "$PROPOSALS_DIR"
+
+# emit_proposal <skill> <slug> <type-line> <body>
+# Skips silently if a proposal with the same skill+slug already exists.
+emit_proposal() {
+    local skill=$1 slug=$2 type=$3 body=$4
+    local target="$PROPOSALS_DIR/$DATE-${skill}-${slug}.md"
+
+    if compgen -G "$PROPOSALS_DIR/*-${skill}-${slug}.md" > /dev/null; then
+        echo "  [SKIP] proposal already exists: $skill / $slug"
+        return
+    fi
+
+    cat > "$target" <<EOF
+# Skill Evolution Proposal
+<!-- Auto-generated by scripts/skill-propose.sh on $DATE -->
+<!-- Review and correct any inferences before generating the MR description -->
+<!-- from .gitlab/merge_request_templates/Default.md. -->
+
+**Skill:** ${skill}
+**Type:** ${type}
+**Status:** DRAFT — requires human review before MR
+
+---
+
+${body}
+EOF
+    echo "  [PROPOSAL] $target"
+    GENERATED=$((GENERATED + 1))
+}
+
+# ── Probe 1: coding-testing Layer→Strategy table gaps ────────────────────────
+# Trigger: a new outbound adapter package has no entry in the strategy table.
+probe_testing_layer_strategy() {
+    local skill=".agents/skills/coding-testing/SKILL.md"
+    [[ -f "$skill" ]] || return
+
+    while IFS= read -r dir; do
+        local pkg="${dir##*/}"
+        if grep -q "adapters/outbound/${pkg}" "$skill"; then
+            continue
+        fi
+
+        # Infer strategy from package naming heuristics
+        local strategy=2
+        local note="K8s/HTTP outbound adapter"
+        case "$pkg" in
+            *redis*|*stream*|*queue*|*eventbus*|*message_bus*)
+                strategy=3; note="Redis/stream adapter" ;;
+            *postgres*|*persistence*|*repository*)
+                strategy=5; note="Persistence adapter (requires testcontainers)" ;;
+            *registry*|*noop*)
+                strategy=1; note="Pure unit — no external dependency" ;;
+        esac
+
+        emit_proposal "coding-testing" "layer-strategy-${pkg}" \
+            "New rule — Layer→Strategy table entry" \
+"## What changes
+
+Add \`adapters/outbound/${pkg}/\` → Strategy ${strategy} to the Layer→Strategy decision table in \`SKILL.md\`.
+
+## Evidence
+
+**Trigger:** \`make check-skills\` detected \`internal/adapters/outbound/${pkg}/\` has no strategy mapping.
+
+**Auto-inferred classification:** ${note} → Strategy ${strategy}
+
+> ⚠ Verify this inference is correct by inspecting \`internal/adapters/outbound/${pkg}/\`
+> before submitting. Wrong strategy mapping is worse than no mapping.
+
+| Metric | Value |
+|--------|-------|
+| Detected by | \`make check-skills\` |
+| Package path | \`internal/adapters/outbound/${pkg}/\` |
+| Inferred strategy | ${strategy} |
+
+## TODO before submitting as MR
+
+- [ ] Open \`internal/adapters/outbound/${pkg}/\` and confirm strategy ${strategy} is correct
+- [ ] Add the line to SKILL.md Layer→Strategy table
+- [ ] If a new infrastructure pattern is involved, update the relevant strategy detail file
+- [ ] Run \`make check-skills\` — should pass after your edit"
+    done < <(find internal/adapters/outbound -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+}
+
+# ── Probe 2: coding-testing missing template references ──────────────────────
+# Trigger: a strategy file references a template that doesn't exist.
+probe_testing_missing_templates() {
+    for strategy_file in .agents/skills/coding-testing/strategies/*.md; do
+        [[ -f "$strategy_file" ]] || continue
+        while IFS= read -r raw; do
+            local tpl="${raw#templates/}"
+            if [[ ! -f ".agents/skills/coding-testing/templates/$tpl" ]]; then
+                local base="${tpl%.*}"
+                emit_proposal "coding-testing" "missing-template-${base}" \
+                    "Missing template file" \
+"## What changes
+
+Strategy file \`${strategy_file##*/}\` references a template that does not exist:
+\`.agents/skills/coding-testing/templates/${tpl}\`
+
+## Evidence
+
+**Trigger:** \`scripts/skill-propose.sh\` detected a broken template reference.
+
+## TODO
+
+- [ ] Create the missing template, or remove the reference from the strategy file
+- [ ] Generate an MR description from the standard template and submit via \`make open-mr ... ARGS=\"--body-file ...\"\`"
+            fi
+        done < <(grep -o 'templates/[^ )]*' "$strategy_file" || true)
+    done
+}
+
+# ── Probe 3: coding-architecture application/port/ inventory drift ───────────────────
+# Trigger: a port file exists in code but isn't listed in the inventory table.
+probe_architecture_ports() {
+    local skill=".agents/skills/coding-architecture/SKILL.md"
+    [[ -f "$skill" ]] || return
+
+    for port_file in internal/application/port/*.go; do
+        [[ -f "$port_file" ]] || continue
+        local base="${port_file##*/}"
+
+        # Skip generated and helper files that aren't supposed to be in the table
+        case "$base" in
+            *_test.go) continue ;;
+        esac
+
+        # Inventory entries are written as backtick-wrapped filenames, e.g. `embedding.go`
+        if grep -qF "\`${base}\`" "$skill"; then
+            continue
+        fi
+
+        emit_proposal "coding-architecture" "port-inventory-${base%.go}" \
+            "Port inventory drift — file not listed" \
+"## What changes
+
+The file \`internal/application/port/${base}\` exists in the codebase but is not
+listed in the \`application/port/\` inventory table in \`SKILL.md\`. Either add
+it to the table (with interface name + primary user) or document it as a helper-only file.
+
+## Evidence
+
+**Trigger:** \`scripts/skill-propose.sh\` scanned \`internal/application/port/*.go\`
+and found \`${base}\` is not mentioned in \`coding-architecture/SKILL.md\`.
+
+## TODO before submitting as MR
+
+- [ ] Open \`internal/application/port/${base}\` and identify the exported interface (or helpers)
+- [ ] Add a row to the \`application/port/\` inventory table
+- [ ] Generate an MR description from the standard template and submit via \`make open-mr ... ARGS=\"--body-file ...\"\`"
+    done
+}
+
+# ── Probe 4: coding-runtime-adapter runtime adapter not registered ──────────────────
+# Trigger: a directory under outbound/ has BOTH executor.go AND controller.go
+# (the canonical "full runtime" signature) but is not mentioned in
+# coding-runtime-adapter's existing-providers reference.
+probe_runtime_adapters() {
+    local skill=".agents/skills/coding-runtime-adapter/SKILL.md"
+    [[ -f "$skill" ]] || return
+
+    for ctl_file in internal/adapters/outbound/*/controller.go; do
+        [[ -f "$ctl_file" ]] || continue
+        local dir="${ctl_file%/controller.go}"
+        [[ -f "$dir/executor.go" ]] || continue   # full-runtime gate
+
+        local pkg="${dir##*/}"
+        local pkg_cap
+        pkg_cap="$(printf '%s' "${pkg:0:1}" | tr '[:lower:]' '[:upper:]')${pkg:1}"
+
+        # Already mentioned in bandari? Look for `pkg` in EngineKind cells, table cells, or prose
+        if grep -qE "(\b${pkg}\b|EngineKind${pkg_cap})" "$skill"; then
+            continue
+        fi
+
+        # Probe each component of the quad for completeness
+        local missing=()
+        [[ -f "$dir/discovery.go" ]] || missing+=("discovery.go")
+        local has_cred=0 cred
+        for cred in "$dir"/apikey*.go "$dir"/token*.go "$dir"/credential*.go; do
+            [[ -f "$cred" && "$cred" != *_test.go ]] || continue
+            has_cred=1
+            break
+        done
+        [[ "$has_cred" -eq 1 ]] || missing+=("credential file (apikey.go / token.go / credential*.go)")
+
+        local missing_summary="(quad complete)"
+        if [[ ${#missing[@]} -gt 0 ]]; then
+            missing_summary="missing: $(IFS=', '; echo "${missing[*]}")"
+        fi
+
+        emit_proposal "coding-runtime-adapter" "runtime-${pkg}" \
+            "New runtime adapter not registered" \
+"## What changes
+
+A new runtime adapter exists at \`internal/adapters/outbound/${pkg}/\` (with both
+\`executor.go\` and \`controller.go\`) but is not mentioned in \`coding-runtime-adapter/SKILL.md\`.
+Add it to the Existing Providers Quick Reference table and verify the four-file
+quad is complete.
+
+## Evidence
+
+**Trigger:** \`scripts/skill-propose.sh\` scanned \`internal/adapters/outbound/\`
+and found \`${pkg}\` matches the runtime-adapter signature but is not referenced
+in \`coding-runtime-adapter\`.
+
+| Item | Value |
+|---|---|
+| Package path | \`internal/adapters/outbound/${pkg}/\` |
+| Quad status | ${missing_summary} |
+
+## TODO before submitting as MR
+
+- [ ] Confirm \`${pkg}\` is intended as a full runtime provider (not a placeholder)
+- [ ] Verify the four-file quad: \`executor.go\` / \`controller.go\` / \`discovery.go\` / credential file
+- [ ] Add a row to the Existing Providers Quick Reference in \`SKILL.md\`
+- [ ] Add \`EngineKind${pkg_cap}\` to \`internal/domain/shared/enums.go\` if not present
+- [ ] Wire in \`internal/bootstrap/worker/registry.go\` via \`reg.Register(...)\`
+- [ ] Reconcile worker config surfaces (see \`coding-deploy-config\` 5-surface gate)"
+    done
+}
+
+# ── Probe 5: coding-http-api IDL service has no handler binding ──────────────────
+# Trigger: an IDL `service XxxService { ... }` has no compile-time interface
+# assertion (`var _ <pkg>.XxxService = (*<H>Handler)(nil)`) in any handler.
+probe_http_api_idl_handlers() {
+    local handlers_glob='internal/adapters/inbound/http/handlers/*.go'
+
+    while IFS= read -r service_name; do
+        [[ -n "$service_name" ]] || continue
+
+        # Look for `var _ <pkg>.<ServiceName> = (`-style interface assertion
+        if grep -qE "\.${service_name}[[:space:]]*=[[:space:]]*\(" $handlers_glob 2>/dev/null; then
+            continue
+        fi
+
+        local agg
+        agg=$(echo "$service_name" | sed 's/Service$//' | tr '[:upper:]' '[:lower:]')
+
+        emit_proposal "coding-http-api" "idl-handler-${agg}" \
+            "IDL service without handler binding" \
+"## What changes
+
+The Thrift IDL defines \`service ${service_name}\` but no Hertz handler under
+\`internal/adapters/inbound/http/handlers/\` carries a compile-time
+interface-assertion line of the form:
+\`\`\`go
+var _ <pkg>.${service_name} = (*<Handler>)(nil)
+\`\`\`
+
+Either implement the handler, OR if the service is intentionally deferred,
+document it as \`[规划中]\` per \`docs/CONVENTIONS.md\` and explicitly note the
+gap in the relevant component doc.
+
+## Evidence
+
+**Trigger:** \`scripts/skill-propose.sh\` cross-referenced \`api/idl/*.thrift\`
+service definitions against \`var _ <pkg>.<ServiceName> = (\` assertions in
+the handlers directory and found no match for \`${service_name}\`.
+
+## TODO before submitting as MR
+
+- [ ] Decide intent: implement now, or mark \`[规划中]\` in the component doc
+- [ ] If implementing: create handler file, add interface assertion line
+- [ ] If deferring: open an issue tracking the work, link from doc
+- [ ] If skill rule needs an exception clause for known-deferred services, update SKILL.md"
+    done < <(grep -hE '^[[:space:]]*service [A-Z][A-Za-z]+' api/idl/*.thrift 2>/dev/null \
+            | awk '{print $2}' | sort -u)
+}
+
+# ── Run all probes ──────────────────────────────────────────────────────────
+
+probe_testing_layer_strategy
+probe_testing_missing_templates
+probe_architecture_ports
+probe_runtime_adapters
+probe_http_api_idl_handlers
+
+echo ""
+if [ "$GENERATED" -eq 0 ]; then
+    echo "  [OK] No skill gaps detected — no proposals generated"
+else
+    echo "  [$GENERATED proposal(s) created in $PROPOSALS_DIR/]"
+    echo "  Review each file, correct inferences, then submit as MR."
+fi

package/templates/scripts/skill-router-hook.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# Path-triggered skill-router hook — nudges an agent to invoke the relevant
+# coding-* skill whenever an edit touches a path with a known skill mapping.
+#
+# Currently wired by Claude Code through .claude/settings.json
+# hooks.PostToolUse. Other tools may reuse this script if they provide the same
+# JSON shape on stdin or wrap it with an adapter.
+#
+# Input contract: JSON containing .tool_name and .tool_input.file_path.
+# Output contract: Claude-compatible hookSpecificOutput.additionalContext.
+#
+# This script is a thin mirror of the §Skill Router table in AGENTS.md.
+# AGENTS.md is the cross-tool source of truth; when the table changes, update
+# AGENTS.md first, then mirror in this file and .cursor/rules/skill-router.mdc.
+# `make check-skill-router-sync` (in `make check` + pre-commit) fails the build
+# if the three mirrors drift, so a forgotten mirror is caught, not silent.
+#
+# Performance note: this fires on EVERY Edit/Write tool call. Hot path is
+# kept minimal — read stdin once, single jq invocation, and resolve the repo
+# root only when an edit-capable tool provides a file path.
+
+set -euo pipefail
+
+# Skip silently if jq is missing (don't break the user's session)
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Single jq call extracts both fields as a tab-separated record
+INPUT=$(cat 2>/dev/null || true)
+[[ -z "$INPUT" ]] && exit 0
+IFS=$'\t' read -r TOOL FILE < <(
+    printf '%s' "$INPUT" | jq -r '[.tool_name // "", .tool_input.file_path // ""] | @tsv'
+)
+
+case "$TOOL" in
+    Edit|Write|MultiEdit|NotebookEdit) ;;
+    *) exit 0 ;;
+esac
+[[ -z "$FILE" ]] && exit 0
+
+# Repo root: prefer the harness-provided env var, fall back to git. Do not
+# require a specific checkout directory name; CI may check the repo out at
+# /home/code while local worktrees often end in coding_engine.
+REPO="${CLAUDE_PROJECT_DIR:-}"
+if [[ -n "$REPO" ]]; then
+    REPO="${REPO%/}"
+else
+    REPO=$(git -C "$(dirname "$FILE")" rev-parse --show-toplevel 2>/dev/null || true)
+fi
+[[ -z "$REPO" ]] && exit 0
+
+REL="${FILE#"$REPO"/}"
+[[ "$REL" == "$FILE" ]] && exit 0   # path was outside repo
+
+# ── Path → skill mapping ─────────────────────────────────────────────────────
+SKILL=""
+REASON=""
+
+case "$REL" in
+    # Redis-backed code — cluster compatibility plus test strategy both apply.
+    internal/adapters/outbound/**/redis*.go | \
+    internal/adapters/outbound/eventbus/* | \
+    internal/adapters/outbound/messagebus/* | \
+    internal/adapters/outbound/presence/* | \
+    internal/adapters/outbound/lane/redislane/* | \
+    internal/adapters/outbound/sessionlease/* | \
+    pkg/platform/redis/*)
+        SKILL="coding-architecture and coding-testing"
+        REASON="Redis-backed code — covers single/sentinel/cluster compatibility, Lua hash tags, and miniredis/testcontainer strategy" ;;
+
+    # Tests — covers the 5 strategies and t.Parallel/race conventions.
+    *_test.go | tests/*)
+        SKILL="coding-testing"
+        REASON="tests — covers the 5 strategies and t.Parallel/race conventions" ;;
+
+    # Runtime adapters — executor/controller, provider registry, and config sync.
+    internal/adapters/outbound/hermes/* | \
+    internal/adapters/outbound/workspacejob/* | \
+    internal/bootstrap/worker/registry.go)
+        SKILL="coding-runtime-adapter and coding-deploy-config"
+        REASON="runtime adapter — covers Executor/Controller, CRD/StatefulSet patterns, worker provider wiring, and config sync gate" ;;
+
+    # Schema — explicit SQL migrations own coding-engine main DB schema.
+    internal/adapters/outbound/persistence/rdb/po/* | \
+    migration/*)
+        SKILL="coding-db-schema"
+        REASON="schema change — explicit migration SQL, RDB repository behavior, and forward-only safety apply" ;;
+
+    # IDL / handlers / generated OpenAPI HTML — cross-layer cleanup and OpenAPI sync.
+    api/idl/*.thrift | \
+    internal/adapters/inbound/http/handlers/* | \
+    docs/openapi/coding-engine-api.html)
+        SKILL="coding-http-api"
+        REASON="HTTP API surface — IDL/handler/frontend and OpenAPI YAML + HTML must align" ;;
+
+    # Observability — collector binary, otel pipeline, metrics catalogue.
+    # Listed BEFORE the deploy-config catch-all so collector chart templates
+    # route to the more-specific observability skill. Glob shape matches
+    # AGENTS.md §Skill Router (`configs/otel*.yaml*` covers otel-config.yaml,
+    # otel-config.yaml.example, and otelcol-build-config.yaml).
+    internal/observability/* | \
+    pkg/platform/telemetrydb/* | \
+    coding-otelcol/* | \
+    configs/otel*.yaml* | \
+    build/docker/otelcol.Dockerfile | \
+    deployments/coding-engine/templates/collector/*)
+        SKILL="coding-observability"
+        REASON="observability — metric catalogue + smoke guard, port.Metrics DI shape, ocb collector pipeline (ADR-0023)" ;;
+
+    # Deployment / config — 5-surface sync.
+    deployments/* | \
+    configs/engine.yaml* | \
+    internal/bootstrap/app/engine_config.go | \
+    internal/adapters/outbound/*/config.go)
+        SKILL="coding-deploy-config"
+        REASON="deployment/config — 5-surface sync gate applies" ;;
+
+    # New aggregate / port — DDD layer map and ServiceDeps shape.
+    internal/domain/* | \
+    internal/application/port/* | \
+    internal/application/*/service.go)
+        SKILL="coding-architecture"
+        REASON="aggregate/port — DDD layer map and ServiceDeps shape" ;;
+esac
+
+# ── ADR-trigger note ─────────────────────────────────────────────────────────
+# Architectural-surface edits may warrant an ADR. Narrow set (3 strongest
+# "new architectural surface" signals) to avoid alert fatigue; appended to the
+# advisory context below rather than emitted separately, to stay on the hot path.
+ADR_NOTE=""
+case "$REL" in
+    internal/domain/* | \
+    internal/application/port/* | \
+    api/idl/*.thrift)
+        ADR_NOTE=" If this introduces or reverses an architectural decision, record an ADR (see docs/adr/CONVENTIONS.md, Mode A/B)." ;;
+esac
+
+[[ -z "$SKILL" ]] && exit 0
+
+# Emit advisory context for the next turn. The host agent reads
+# additionalContext but is not forced to invoke; the skill advisory is a nudge,
+# not an enforcement gate.
+jq -n \
+    --arg skill "$SKILL" \
+    --arg rel "$REL" \
+    --arg reason "$REASON" \
+    --arg adr "$ADR_NOTE" \
+    '{
+        hookSpecificOutput: {
+            hookEventName: "PostToolUse",
+            additionalContext: ("[skill-router] Edit touched `" + $rel + "`. The `" + $skill + "` skill(s) apply (" + $reason + ")." + $adr + " Invoke the relevant skill tool if you have not already in this turn.")
+        }
+    }'