trae-coding-engine 0.1.0

package/templates/scripts/check-skills.sh

@@ -0,0 +1,243 @@
+#!/usr/bin/env bash
+# Skill governance hard checks for every skill under .agents/skills/coding-*.
+#
+# Hard checks (FAIL on violation):
+#   1. SKILL.md exists
+#   2. Frontmatter contains: name, description
+#   3. Frontmatter `name` matches the directory name
+#   4. Internal refs — `.agents/skills/<name>/(patterns|templates)/<file>` exist
+#   5. Drift detection — repo-rooted paths cited in SKILL.md exist on disk
+#      (literal paths starting with internal/, docs/, migrations/, api/, etc.)
+#   6. coding-testing Layer→Strategy table covers every outbound adapter package
+#   7. Application code does not silently replace missing injected loggers with logger.NewNop()
+#
+# Soft checks (WARN, no FAIL):
+#   8. Skill cross-reference graph drift
+#
+# This script intentionally keeps semantic checks small and repo-specific.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+# shellcheck source=scripts/lib/skill-frontmatter.sh
+. scripts/lib/skill-frontmatter.sh
+# shellcheck source=scripts/lib/doc-drift.sh
+. scripts/lib/doc-drift.sh
+
+GLOBAL_VIOLATIONS=0
+
+# Materialise the set of real *.go basenames once for the bare-filename drift
+# check (── 5b ──). Tables that cite a single `foo.go` whose basename exists
+# nowhere in the repo are flagged.
+DOC_DRIFT_GO_BASENAMES="$(mktemp)"
+trap 'rm -f "$DOC_DRIFT_GO_BASENAMES"' EXIT
+doc_drift_go_basenames_to "$DOC_DRIFT_GO_BASENAMES"
+
+# Repo-rooted prefixes for drift detection. Anything matching one of these
+# at the start of a token is treated as a real path that must exist on disk.
+DRIFT_PREFIXES='^(internal|docs|migrations|api|configs|deployments|scripts|cmd|pkg|tests|tools|web|gen)/'
+
+check_skill() {
+    local dir=$1
+    local name
+    name=$(basename "$dir")
+    local skill_md="$dir/SKILL.md"
+    local violations=0
+
+    echo "── $name ─────────────────────────────────────"
+
+    if [[ ! -f "$skill_md" ]]; then
+        echo "  [FAIL] $skill_md missing"
+        GLOBAL_VIOLATIONS=$((GLOBAL_VIOLATIONS+1))
+        return
+    fi
+
+    # ── 1+2+3. Frontmatter sanity ─────────────────────────────────────────
+    for field in name description; do
+        local val
+        val=$(extract_field "$skill_md" "$field")
+        if [[ -z "$val" ]]; then
+            echo "  [FAIL] frontmatter missing '$field'"
+            violations=$((violations+1))
+        fi
+    done
+
+    local declared_name
+    declared_name=$(extract_field "$skill_md" "name")
+    if [[ -n "$declared_name" ]] && [[ "$declared_name" != "$name" ]]; then
+        echo "  [FAIL] frontmatter name='$declared_name' but directory is '$name'"
+        violations=$((violations+1))
+    fi
+
+    # ── 4. Internal refs ──────────────────────────────────────────────────
+    local internal_pattern="\.agents/skills/${name}/(patterns|templates)/[a-zA-Z0-9._-]+"
+    local internal_refs
+    internal_refs=$(grep -oE "$internal_pattern" "$skill_md" | sort -u || true)
+    local internal_count=0
+    if [[ -n "$internal_refs" ]]; then
+        while IFS= read -r ref; do
+            [[ -z "$ref" ]] && continue
+            internal_count=$((internal_count+1))
+            if [[ ! -f "$ref" ]]; then
+                echo "  [FAIL] internal ref missing: $ref"
+                violations=$((violations+1))
+            fi
+        done <<< "$internal_refs"
+    fi
+
+    # ── 5. Drift detection — external repo paths ────────────────────────
+    # Extract candidate paths: tokens that look like a real file/dir
+    # rooted at one of the known repo prefixes. We trim trailing :NN line
+    # numbers and trailing punctuation, and skip placeholder paths
+    # containing < > * { or ellipsis-style segments.
+    local drift_count=0
+    local drift_broken=0
+    while IFS= read -r raw; do
+        [[ -z "$raw" ]] && continue
+
+        # Strip trailing line ref like ":123"
+        local p="${raw%%:[0-9]*}"
+        # Strip trailing punctuation common in markdown prose
+        p="${p%[\.\,\)\;\]\`]}"
+
+        # Skip placeholders / globs / shell expansion patterns
+        case "$p" in
+            *\<* | *\>* | *\** | *\{* | *\$* )
+                continue ;;
+        esac
+
+        # Skip tokens ending in connective chars — these are typically
+        # captures truncated at a `<placeholder>` boundary, e.g.
+        # `deployments/coding-<svc>/...` → grep -oE stops at `<` and yields
+        # `deployments/coding-`. Real paths in this repo never end in
+        # `-`, `_`, `=`, or a bare `.`.
+        case "$p" in
+            *-|*_|*=|*.) continue ;;
+        esac
+
+        # Skip if any path segment is an all-caps placeholder run
+        # (`NNNNNN`, `XX`, `0N`) — these are doc conventions, not real names
+        if [[ "$p" =~ (^|/)(N{2,}|X{2,}|0N)([_.-]|$|/) ]]; then
+            continue
+        fi
+
+        # Re-check the trimmed token still starts with a known prefix
+        # (the regex below is the one used to match in the first place,
+        # but `${var%...}` may have stripped past the prefix in pathological
+        # cases — be defensive)
+        if ! [[ "$p" =~ $DRIFT_PREFIXES ]]; then
+            continue
+        fi
+
+        drift_count=$((drift_count+1))
+
+        # `-e` matches both files and directories — covers the
+        # "internal/foo/" trailing-slash case the extractor produces.
+        if [[ -e "$p" ]]; then
+            continue
+        fi
+
+        echo "  [FAIL] drift — referenced path missing: $p"
+        violations=$((violations+1))
+        drift_broken=$((drift_broken+1))
+    done < <(grep -oE '[A-Za-z0-9_./-]+' "$skill_md" | grep -E "$DRIFT_PREFIXES" | sort -u || true)
+
+    # ── 5b. Bare *.go filenames in tables ─────────────────────────────────
+    # The §5 drift check above only matches repo-rooted paths (internal/…).
+    # File-inventory tables, however, cite bare basenames like `volcid.go` in
+    # the first column — invisible to §5. Flag any such cell whose basename
+    # exists nowhere in the repo (deleted/renamed file still documented).
+    while IFS= read -r hit; do
+        [[ -z "$hit" ]] && continue
+        echo "  [FAIL] drift — table cites non-existent Go file: ${hit##*: }"
+        violations=$((violations+1))
+        drift_broken=$((drift_broken+1))
+    done < <(doc_drift_check_table_go "$skill_md")
+
+    # ── Summary line per skill ───────────────────────────────────────────
+    if [[ "$violations" -eq 0 ]]; then
+        local drift_summary=""
+        if [[ "$drift_count" -gt 0 ]]; then
+            drift_summary=", $drift_count drift refs resolved"
+        fi
+        echo "  [OK] frontmatter valid, ${internal_count} internal refs resolved${drift_summary}"
+    else
+        GLOBAL_VIOLATIONS=$((GLOBAL_VIOLATIONS+violations))
+    fi
+}
+
+if [[ ! -d "$SKILLS_ROOT" ]]; then
+    echo "[ERROR] $SKILLS_ROOT not found" >&2
+    exit 1
+fi
+
+# ── Application logger injection guard ───────────────────────────────────────
+# Business/application constructors must fail fast when a logger dependency is
+# missing. Tests can pass logger.NewNop() explicitly, but production code must
+# not hide a DI wiring bug by silently creating one.
+echo "── application-logger-injection ─────────────────────────────────────"
+LOGGER_FALLBACK_HITS=$(
+    grep -RIn --include='*.go' 'logger\.NewNop()' internal/application 2>/dev/null \
+        | grep -v '_test.go' || true
+)
+if [[ -n "$LOGGER_FALLBACK_HITS" ]]; then
+    echo "$LOGGER_FALLBACK_HITS" | sed 's/^/  [FAIL] /'
+    echo "  [HINT] Inject logger.Logger via deps/fx; tests may pass logger.NewNop() explicitly."
+    GLOBAL_VIOLATIONS=$((GLOBAL_VIOLATIONS+1))
+else
+    echo "  [OK] no logger.NewNop() fallback in internal/application non-test code"
+fi
+
+# ── coding-testing Layer→Strategy coverage ───────────────────────────────────
+# Every outbound adapter package needs an explicit testing strategy entry so
+# new adapters do not silently skip the test ownership rule.
+echo "── coding-testing-layer-strategy ─────────────────────────────────────"
+TESTING_SKILL="$SKILLS_ROOT/coding-testing/SKILL.md"
+if [[ ! -f "$TESTING_SKILL" ]]; then
+    echo "  [FAIL] $TESTING_SKILL missing"
+    GLOBAL_VIOLATIONS=$((GLOBAL_VIOLATIONS+1))
+else
+    HAS_MISSING=0
+    for dir in internal/adapters/outbound/*; do
+        [[ -d "$dir" ]] || continue
+        pkg=$(basename "$dir")
+        if ! grep -q "adapters/outbound/$pkg" "$TESTING_SKILL"; then
+            echo "  [FAIL] adapters/outbound/$pkg has no Layer→Strategy table entry"
+            HAS_MISSING=1
+            GLOBAL_VIOLATIONS=$((GLOBAL_VIOLATIONS+1))
+        fi
+    done
+    if [[ "$HAS_MISSING" -eq 0 ]]; then
+        echo "  [OK] all outbound adapter packages covered"
+    fi
+fi
+
+echo ""
+
+for dir in "$SKILLS_ROOT"/coding-*; do
+    [[ -d "$dir" ]] || continue
+    check_skill "$dir"
+done
+
+# ── Cross-reference graph drift (soft warning) ───────────────────────────────
+# Almost-free: regenerate the DOT in-memory and compare to the committed copy.
+# Drift here is informational, not a hard failure (the graph is a derived
+# artifact; tests / functionality don't depend on it being current).
+if [[ -x scripts/skill-graph.sh ]]; then
+    echo ""
+    echo "── skill-graph ─────────────────────────────────────"
+    if bash scripts/skill-graph.sh --check >/dev/null 2>&1; then
+        echo "  [OK] docs/assets/skill-graph.dot matches current cross-references"
+    else
+        echo "  [STALE] docs/assets/skill-graph.dot is out of sync with SKILL.md cross-references"
+        echo "          run \`make skill-graph\` to regenerate, then commit the diff"
+    fi
+fi
+
+echo ""
+if [[ "$GLOBAL_VIOLATIONS" -gt 0 ]]; then
+    echo "[FAIL] $GLOBAL_VIOLATIONS violation(s)"
+    exit 1
+fi
+echo "[OK] all skills pass structural integrity check"

package/templates/scripts/docs-audit-to-issues.py

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+"""File docs-audit implementation follow-ups as Codebase issues."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shlex
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+DEFAULT_REPORT = "docs-audit-notification-report.md"
+DEFAULT_SUMMARY = "docs-audit-code-issues.md"
+SEVERITY_RANK = {
+    "Suggestion": 0,
+    "Minor": 1,
+    "Major": 2,
+    "Critical": 3,
+}
+FINDING_RE = re.compile(r"(?m)^#{1,6} \[(Critical|Major|Minor|Suggestion)\]\s+(.+?)\s*$")
+AFTER_FINDINGS_RE = re.compile(
+    r"(?m)^#{1,6} (按人员整理的任务|按责任人归总的任务清单|待确认问题|执行过的关键命令)\s*$"
+)
+PEOPLE_RE = re.compile(r"(?m)^#{1,6} (按人员整理的任务|按责任人归总的任务清单)\s*$")
+NEXT_SECTION_RE = re.compile(r"(?m)^#{1,6} (待确认问题|执行过的关键命令)\s*$")
+PERSON_HEADING_RE = re.compile(r"^#{1,6}\s+`?(.+?)`?\s*$")
+TASK_RE = re.compile(r"^\s*[-*]\s+`?\[(Critical|Major|Minor|Suggestion)\]\s+(.+?)`?[：:].*$")
+EMAIL_RE = re.compile(r"[\w.+-]+@bytedance\.com", re.IGNORECASE)
+PATH_RE = re.compile(r"`([^`]+?)(?::\d+)?`")
+
+
+@dataclass
+class Finding:
+    severity: str
+    title: str
+    body: str
+    assignee_emails: set[str] = field(default_factory=set)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Create Codebase issues for docs-audit findings left for implementation follow-up."
+    )
+    parser.add_argument("--report", default=DEFAULT_REPORT)
+    parser.add_argument("--summary", default=DEFAULT_SUMMARY)
+    parser.add_argument(
+        "--min-severity",
+        default="Major",
+        choices=("Suggestion", "Minor", "Major", "Critical"),
+        help="minimum severity to file, default: Major",
+    )
+    parser.add_argument(
+        "--apply",
+        action="store_true",
+        help="create issues; without this, only print dry-run commands",
+    )
+    parser.add_argument(
+        "--actor",
+        default=os.environ.get("CODING_ISSUE_AUTODEV_ACTOR", "human"),
+        choices=("human", "agent"),
+        help="issue API mode passed to scripts/open-issue.sh (default: env CODING_ISSUE_AUTODEV_ACTOR or human)",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    report_path = Path(args.report)
+    summary_path = Path(args.summary)
+    if not report_path.is_file():
+        write_summary(summary_path, ["## 代码跟进 Issue", "", f"- 未提交：报告文件不存在 `{report_path}`。"])
+        print(f"error: report file not found: {report_path}", file=sys.stderr)
+        return 2
+
+    report = report_path.read_text(encoding="utf-8")
+    findings = [
+        f
+        for f in parse_findings(report)
+        if SEVERITY_RANK.get(f.severity, 0) >= SEVERITY_RANK[args.min_severity]
+    ]
+    if not findings:
+        write_summary(
+            summary_path,
+            [
+                "## 代码跟进 Issue",
+                "",
+                f"- 未提交：`{report_path}` 中没有 {args.min_severity} 及以上需要代码/配置/实现跟进的差异点。",
+            ],
+        )
+        print("[docs-audit-to-issues] no findings above severity gate", file=sys.stderr)
+        return 0
+
+    failures = 0
+    summary = ["## 代码跟进 Issue", ""]
+    for finding in findings:
+        assignee_ids: list[str] = []
+        unresolved: list[str] = []
+        for email in sorted(finding.assignee_emails):
+            user_id = resolve_user_id(email)
+            if user_id:
+                assignee_ids.append(user_id)
+            else:
+                unresolved.append(email)
+
+        issue_body = build_issue_body(finding, report_path)
+        dedup_key = "docs-audit:" + hashlib.sha1(
+            f"{finding.severity}|{finding.title}|{first_evidence_token(finding.body)}".encode("utf-8")
+        ).hexdigest()[:16]
+        cmd = [
+            "scripts/open-issue.sh",
+            "--title",
+            f"[docs-audit] {finding.title}",
+            "--status",
+            "todo",
+            "--dedup-key",
+            dedup_key,
+            "--actor",
+            args.actor,
+        ]
+        for assignee_id in assignee_ids:
+            cmd.extend(["--assignee", assignee_id])
+
+        with tempfile.NamedTemporaryFile("w", encoding="utf-8", delete=False) as fp:
+            fp.write(issue_body)
+            body_path = Path(fp.name)
+        try:
+            cmd.extend(["--body-file", str(body_path)])
+            if not args.apply:
+                cmd.append("--dry-run")
+            print(
+                f"[docs-audit-to-issues] {'creating' if args.apply else 'dry-run'} issue: "
+                f"[{finding.severity}] {finding.title}",
+                file=sys.stderr,
+            )
+            result = subprocess.run(cmd, text=True, capture_output=True, check=False)
+        finally:
+            body_path.unlink(missing_ok=True)
+
+        output = (result.stdout + "\n" + result.stderr).strip()
+        if result.returncode != 0:
+            failures += 1
+            log_issue_failure(
+                label=f"[{finding.severity}] {finding.title}",
+                dedup_key=dedup_key,
+                assignees=format_people(finding.assignee_emails, assignee_ids, unresolved),
+                cmd=cmd,
+                result=result,
+            )
+            summary.extend(
+                [
+                    f"- 创建失败：`[{finding.severity}] {finding.title}`",
+                    f"  - dedup：`{dedup_key}`",
+                    f"  - 负责人：{format_people(finding.assignee_emails, assignee_ids, unresolved)}",
+                    f"  - 错误：{one_line(output)}",
+                ]
+            )
+            continue
+
+        issue_ref = parse_issue_ref(output)
+        verb = "已提交/复用" if args.apply else "dry-run"
+        summary.extend(
+            [
+                f"- {verb}：{issue_ref or f'`[{finding.severity}] {finding.title}`'}",
+                f"  - 差异点：`[{finding.severity}] {finding.title}`",
+                f"  - 负责人：{format_people(finding.assignee_emails, assignee_ids, unresolved)}",
+                f"  - dedup：`{dedup_key}`",
+            ]
+        )
+
+    write_summary(summary_path, summary)
+    if failures:
+        print(f"[docs-audit-to-issues] failed to create {failures} issue(s)", file=sys.stderr)
+        return 1
+    return 0
+
+
+def parse_findings(report: str) -> list[Finding]:
+    findings: list[Finding] = []
+    matches = list(FINDING_RE.finditer(report))
+    task_emails = parse_task_emails(report)
+    for idx, match in enumerate(matches):
+        severity = match.group(1)
+        title = match.group(2).strip()
+        start = match.start()
+        if idx + 1 < len(matches):
+            end = matches[idx + 1].start()
+        else:
+            next_section = AFTER_FINDINGS_RE.search(report, match.end())
+            end = next_section.start() if next_section else len(report)
+        body = report[start:end].strip()
+        emails = set(task_emails.get(normalize_title(title), set()))
+        emails.update(email.lower() for email in EMAIL_RE.findall(body))
+        findings.append(Finding(severity=severity, title=title, body=body, assignee_emails=emails))
+    return findings
+
+
+def parse_task_emails(report: str) -> dict[str, set[str]]:
+    match = PEOPLE_RE.search(report)
+    if not match:
+        return {}
+    section = report[match.start() :]
+    next_match = NEXT_SECTION_RE.search(section)
+    if next_match:
+        section = section[: next_match.start()]
+
+    result: dict[str, set[str]] = {}
+    current_emails: set[str] = set()
+    for line in section.splitlines()[1:]:
+        heading = PERSON_HEADING_RE.match(line)
+        if heading:
+            current_emails = {email.lower() for email in EMAIL_RE.findall(heading.group(1))}
+            continue
+        task = TASK_RE.match(line)
+        if task and current_emails:
+            result.setdefault(normalize_title(task.group(2)), set()).update(current_emails)
+    return result
+
+
+def normalize_title(title: str) -> str:
+    return re.sub(r"\s+", " ", title.strip()).strip("`：:")
+
+
+def resolve_user_id(email: str) -> str | None:
+    username = email.split("@", 1)[0]
+    try:
+        result = subprocess.run(
+            ["codebase", "user", "view", username],
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        print(f"[docs-audit-to-issues] codebase CLI not found while resolving assignee: {email}", file=sys.stderr)
+        return None
+    if result.returncode != 0:
+        print(
+            f"[docs-audit-to-issues] failed to resolve assignee {email}: "
+            f"codebase user view {username} exited {result.returncode}: {one_line(result.stderr or result.stdout)}",
+            file=sys.stderr,
+        )
+        return None
+    try:
+        data = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        print(
+            f"[docs-audit-to-issues] failed to parse codebase user view output for {email}: "
+            f"{one_line(result.stdout)}",
+            file=sys.stderr,
+        )
+        return None
+    if data.get("Error") or data.get("Code"):
+        print(
+            f"[docs-audit-to-issues] codebase user view returned error for {email}: {one_line(result.stdout)}",
+            file=sys.stderr,
+        )
+        return None
+    user_id = data.get("Id")
+    return str(user_id) if user_id else None
+
+
+def evidence_tokens(body: str) -> list:
+    """Extract backtick-wrapped repo-relative paths from an issue body."""
+    # Tolerate an optional `:line` / `:line-line` suffix (real reports cite
+    # `path/file.go:52`); the suffix is stripped so clustering joins on the path.
+    return re.findall(r"`([\w./-]+\.[\w]+)(?::\d+(?:-\d+)?)?`", body)
+
+
+def severity_markers(finding) -> str:
+    """Build machine-readable severity and evidence comment markers."""
+    lines = [f"<!-- severity:{finding.severity} -->"]
+    for token in evidence_tokens(finding.body):
+        lines.append(f"<!-- evidence:{token} -->")
+    return "\n".join(lines)
+
+
+def build_issue_body(finding: Finding, report_path: Path) -> str:
+    body = f"""## Problem
+
+docs-audit 发现文档与实现存在 `{finding.severity}` 级差异，需要代码/配置/实现侧跟进。
+
+## Proposal
+
+请根据差异点确认应补实现、补配置、调整行为，或协调文档侧重新收敛契约。
+
+## Acceptance Criteria
+
+- [ ] 差异点中的代码/配置/实现问题已确认并处理，或给出明确无需改代码的结论。
+- [ ] 如行为发生变化，已同步稳定文档与必要测试。
+- [ ] 相关 MR 关闭本 issue。
+
+## Docs Audit Finding
+
+{finding.body}
+
+---
+source: docs-audit ({report_path})
+"""
+    return body.rstrip() + "\n\n" + severity_markers(finding) + "\n"
+
+
+def first_evidence_token(body: str) -> str:
+    match = PATH_RE.search(body)
+    return match.group(1) if match else body[:120]
+
+
+def parse_issue_ref(output: str) -> str | None:
+    created = re.search(r"created issue #(\d+)(?:\s+\(([^)]+)\))?", output)
+    if created:
+        number = created.group(1)
+        url = created.group(2) or ""
+        return f"#{number}{' ' + url if url else ''}"
+    existing = re.search(r"issue #(\d+) already exists", output)
+    if existing:
+        return f"#{existing.group(1)}（已存在）"
+    return None
+
+
+def format_people(emails: set[str], assignee_ids: list[str], unresolved: list[str]) -> str:
+    if not emails:
+        return "未识别到 `@bytedance.com` 负责人，未指定 assignee"
+    names = ", ".join(f"`{email.split('@', 1)[0]}`" for email in sorted(emails))
+    suffix = []
+    if assignee_ids:
+        suffix.append(f"已指定 {len(assignee_ids)} 人")
+    if unresolved:
+        suffix.append("未解析：" + ", ".join(f"`{email}`" for email in unresolved))
+    return names + ("（" + "；".join(suffix) + "）" if suffix else "")
+
+
+def one_line(text: str) -> str:
+    return re.sub(r"\s+", " ", text).strip()[:240] or "unknown error"
+
+
+def log_issue_failure(
+    *,
+    label: str,
+    dedup_key: str,
+    assignees: str,
+    cmd: list[str],
+    result: subprocess.CompletedProcess[str],
+) -> None:
+    print(f"[docs-audit-to-issues] issue create failed: {label}", file=sys.stderr)
+    print(f"[docs-audit-to-issues] returncode: {result.returncode}", file=sys.stderr)
+    print(f"[docs-audit-to-issues] dedup: {dedup_key}", file=sys.stderr)
+    print(f"[docs-audit-to-issues] assignees: {assignees}", file=sys.stderr)
+    print(f"[docs-audit-to-issues] command: {shlex.join(cmd)}", file=sys.stderr)
+    print_block("[docs-audit-to-issues] stdout", result.stdout)
+    print_block("[docs-audit-to-issues] stderr", result.stderr)
+
+
+def print_block(label: str, text: str, limit: int = 4000) -> None:
+    text = text.strip()
+    if not text:
+        print(f"{label}: <empty>", file=sys.stderr)
+        return
+    if len(text) > limit:
+        text = text[:limit] + "\n...<truncated>"
+    print(f"{label}:\n{text}", file=sys.stderr)
+
+
+def write_summary(path: Path, lines: list[str]) -> None:
+    path.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/scripts/docs-verification-reminder.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Non-blocking pre-commit nudge for Docs Verification Gate.
+#
+# If staged changes touch implementation/config/contract paths but no docs/
+# files, remind the author to check whether documentation needs updates. This
+# is only a nudge, not a real docs audit. OpenAPI generated docs are excluded
+# because they move with the API generation gate.
+
+set -uo pipefail
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  exit 0
+fi
+
+staged="$(git diff --cached --name-only --diff-filter=ACMRD 2>/dev/null || true)"
+if [ -z "$staged" ]; then
+  exit 0
+fi
+
+has_risk=0
+has_docs=0
+risk_paths=()
+
+while IFS= read -r path; do
+  [ -z "$path" ] && continue
+  case "$path" in
+    docs/openapi/*)
+      ;;
+    docs/*)
+      has_docs=1
+      ;;
+  esac
+
+  case "$path" in
+    api/idl/* | \
+    cmd/* | \
+    internal/* | \
+    pkg/* | \
+    configs/* | \
+    deployments/* | \
+    migration/* | \
+    migrations/* | \
+    build/docker/* | \
+    coding-otelcol/*)
+      has_risk=1
+      risk_paths+=("$path")
+      ;;
+  esac
+done <<<"$staged"
+
+if [ "$has_risk" -eq 1 ] && [ "$has_docs" -eq 0 ]; then
+  printf '%s\n' \
+    "Reminder: staged changes touch implementation/config/contract paths but no docs/ files." \
+    "Run the AGENTS.md Docs Verification Gate: grep docs/ for changed identifiers," \
+    "update stable docs if behavior changed, or be ready to explain why docs do not apply." >&2
+  printf 'Changed paths that triggered this reminder:\n' >&2
+  printf '  - %s\n' "${risk_paths[@]:0:8}" >&2
+  if [ "${#risk_paths[@]}" -gt 8 ]; then
+    printf '  - ... (%d more)\n' "$((${#risk_paths[@]} - 8))" >&2
+  fi
+fi
+
+exit 0