fix(lint+scripts): code-reviewer 7개 이슈 일괄 fix + .gitignore

검증 에이전트 보고 7건 모두 재검증 후 CONFIRMED → 적용.

scripts/_doc_lint.py:
- Major: validate_broken_link / validate_cross_link 의 code-fence false
  positive — _strip_code() helper 추가 (```...``` + 인라인 백틱 제거).
  본 fix 없이는 향후 spec 의 예시 link 가 violation 으로 오인식
- Minor: parse_frontmatter 가 trailing inline comment ('foo: bar  # x')
  를 value 로 흡수 → quote 시작 아닌 경우 ' #' 로 split
- Minor: _validate_supersede_chain 의 path depth 가정 (vX.Y.Z 2-level
  하드코딩) → _supersede_base() 도입, meta-level 1-level 평면도 지원

scripts/generate_spec_trace.py:
- Minor: ast.walk 가 class 컨텍스트 평탄화 → class TestFoo: def test_bar
  의 nodeid 가 ::test_bar 만 출력. _SpecMarkerVisitor (NodeVisitor +
  class_stack) 로 정확히 ::TestFoo::test_bar 출력

scripts/update_upstream_pin.py:
- Minor: _previous_pin 의 SemVer 매치 실패 시 (0,0,0) silent fallback
  (전역 fail-fast 정책 위반) → ValueError raise

.github/workflows/docs.yml:
- Minor: paths 의 '**.md' 가 lint 무관 .md (README/CHANGELOG/PR template
  등) 변경에도 fire — 'docs/**' 가 이미 docs 하위 .md 포괄하므로 제거

.gitignore:
- .claude/scheduled_tasks.lock 추가 — ScheduleWakeup hook 의 PID/세션ID
  lock 파일 (런타임 머신-로컬, repo 추적 무의미)

검증: 합성 케이스 4종 (fence false positive / class method / 잘못된
pin key / meta-level supersede) 모두 expected behavior. 기존 lint 0
violation 유지.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DanMeon

.github/workflows/docs.yml

@@ -4,8 +4,9 @@ name: Docs lint
 on:
   push:
     branches: [main]
+    # ^ 'docs/**' 가 docs 안 모든 .md 포괄. README/CHANGELOG 등 lint 무관 .md
+    #   변경에 fire 안 하려고 '**.md' 제외. tests/** 는 spec-trace 검증 때문에 유지.
     paths:
-      - '**.md'
       - 'docs/**'
       - 'tests/**'
       - 'scripts/_doc_lint.py'
@@ -16,7 +17,6 @@ on:
   pull_request:
     branches: [main]
     paths:
-      - '**.md'
       - 'docs/**'
       - 'tests/**'
       - 'scripts/_doc_lint.py'

.gitignore

@@ -40,6 +40,8 @@ coverage.xml
 
 # * Claude Code — settings.json 은 팀 공유 (hooks 등록), local override 만 ignore
 .claude/settings.local.json
+# ^ ScheduleWakeup / 백그라운드 task lock (런타임 PID/세션ID, 머신-로컬)
+.claude/scheduled_tasks.lock
 
 # * Examples 산출물
 render_output/

scripts/_doc_lint.py

@@ -66,13 +66,27 @@ def parse_frontmatter(text: str) -> dict[str, str] | None:
             continue
         k, _, v = line.partition(":")
         v = v.strip()
+        # ^ trailing inline comment ('foo: bar  # note') strip — quoted value 안의
+        #   '#' 는 보호 (flat key:value 가정상 quote 처리 후 안전)
+        if not (v.startswith(("'", '"'))):
+            v = v.split(" #", 1)[0].rstrip()
         # ^ 양쪽 동일 quote 만 unwrap (mismatched 는 그대로)
         if len(v) >= 2 and v[0] == v[-1] and v[0] in ("'", '"'):
             v = v[1:-1]
         meta[k.strip()] = v
     return meta
 
 
+# * code fence stripper — fence 안 예시 link / 백틱 인라인 link 를 lint 대상에서 배제
+def _strip_code(text: str) -> str:
+    """Remove ```...``` 블록 + 인라인 `...` 백틱. lint regex 는 raw text 가
+    아니라 본 출력에 적용 — fence 안 예시 link 가 broken/cross-link 위반으로
+    오인식되는 false positive 방지."""
+    text = re.sub(r"```.*?```", "", text, flags=re.DOTALL)
+    text = re.sub(r"`[^`\n]+`", "", text)
+    return text
+
+
 # * Rule 1+2: frontmatter schema + supersede chain
 def validate_frontmatter(rel_str: str, meta: dict[str, str], repo: Path) -> list[str]:
     errors: list[str] = []
@@ -138,8 +152,12 @@ def _validate_supersede_chain(rel_str: str, meta: dict[str, str], repo: Path) ->
     rel = Path(rel_str)
 
     superseded_by = meta.get("superseded_by")
+    # ^ supersede 경로 base: vX.Y.Z 하위면 docs/<kind>/, meta-level 평면이면 docs/<kind>/
+    #   format: vX.Y.Z 파일은 '<vX.Y.Z>/<topic>.md', meta-level 은 '<topic>.md'.
+    base, expected = _supersede_base(rel)
+
     if superseded_by:
-        target_rel = rel.parent.parent / superseded_by
+        target_rel = base / superseded_by
         target = repo / target_rel
         if not target.exists():
             errors.append(
@@ -151,18 +169,16 @@ def _validate_supersede_chain(rel_str: str, meta: dict[str, str], repo: Path) ->
                 errors.append(
                     f"frontmatter: superseded_by target {superseded_by!r} lacks frontmatter"
                 )
-            else:
-                expected = str(rel.relative_to(rel.parent.parent))
-                if target_meta.get("supersedes") != expected:
-                    errors.append(
-                        f"frontmatter: supersede chain broken — target's "
-                        f"'supersedes' is {target_meta.get('supersedes')!r}, "
-                        f"expected {expected!r}"
-                    )
+            elif target_meta.get("supersedes") != expected:
+                errors.append(
+                    f"frontmatter: supersede chain broken — target's "
+                    f"'supersedes' is {target_meta.get('supersedes')!r}, "
+                    f"expected {expected!r}"
+                )
 
     supersedes = meta.get("supersedes")
     if supersedes:
-        target_rel = rel.parent.parent / supersedes
+        target_rel = base / supersedes
         if not (repo / target_rel).exists():
             errors.append(
                 f"frontmatter: supersedes {supersedes!r} not found (resolved: {target_rel})"
@@ -171,6 +187,19 @@ def _validate_supersede_chain(rel_str: str, meta: dict[str, str], repo: Path) ->
     return errors
 
 
+def _supersede_base(rel: Path) -> tuple[Path, str]:
+    """supersede chain 의 base 디렉토리 + 본 파일의 expected 역참조 ID.
+
+    vX.Y.Z 파일 (`docs/<kind>/<vX.Y.Z>/<file>.md`) → base=`docs/<kind>/`,
+    expected=`<vX.Y.Z>/<file>.md`.
+    Meta-level 평면 (`docs/<kind>/<file>.md`) → base=`docs/<kind>/`,
+    expected=`<file>.md`.
+    """
+    if re.fullmatch(r"v\d+\.\d+\.\d+", rel.parent.name):
+        return rel.parent.parent, str(rel.relative_to(rel.parent.parent))
+    return rel.parent, rel.name
+
+
 # * Rule 3+4: filename kebab-case + vX.Y.Z directory SemVer
 def validate_filename(rel_str: str) -> list[str]:
     errors: list[str] = []
@@ -242,7 +271,7 @@ def validate_cross_link(rel_str: str, text: str) -> list[str]:
     self_link = f"{base}.md"
 
     errors: list[str] = []
-    for link in re.findall(r"\]\(([^)]+\.md)[^)]*\)", text):
+    for link in re.findall(r"\]\(([^)]+\.md)[^)]*\)", _strip_code(text)):
         link_target = link.split("#")[0]
         if "/" in link_target:
             continue
@@ -262,7 +291,7 @@ def validate_cross_link(rel_str: str, text: str) -> list[str]:
 def validate_broken_link(rel_str: str, text: str, repo: Path) -> list[str]:
     target_dir = (repo / rel_str).parent
     errors: list[str] = []
-    for link in re.findall(r"\]\(([^)]+\.md)[^)]*\)", text):
+    for link in re.findall(r"\]\(([^)]+\.md)[^)]*\)", _strip_code(text)):
         link_target = link.split("#")[0].split("?")[0]
         if not link_target or link_target.startswith("http"):
             continue

scripts/generate_spec_trace.py

@@ -56,7 +56,8 @@ def main(
 
 
 def _collect_spec_markers(tests_dir: Path) -> dict[str, list[str]]:
-    """spec_id → list of pytest nodeids."""
+    """spec_id → list of pytest nodeids. ``class TestFoo`` 안의 메서드도 정확히
+    `tests/x.py::TestFoo::test_bar` 형식으로 출력 (ast.walk 평탄화 회피)."""
     mapping: dict[str, list[str]] = defaultdict(list)
     if not tests_dir.is_dir():
         return mapping
@@ -67,17 +68,44 @@ def _collect_spec_markers(tests_dir: Path) -> dict[str, list[str]]:
         except SyntaxError:
             continue
         rel = py_file.relative_to(REPO)
-        for node in ast.walk(tree):
-            if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
-                if not node.name.startswith("test_"):
-                    continue
-                for decorator in node.decorator_list:
-                    spec_id = _extract_spec_id(decorator)
-                    if spec_id and SPEC_ID_RE.match(spec_id):
-                        mapping[spec_id].append(f"{rel}::{node.name}")
+        visitor = _SpecMarkerVisitor(rel)
+        visitor.visit(tree)
+        for spec_id, nodeids in visitor.mapping.items():
+            mapping[spec_id].extend(nodeids)
     return mapping
 
 
+class _SpecMarkerVisitor(ast.NodeVisitor):
+    """class 컨텍스트 stack 을 유지하며 @pytest.mark.spec(...) 추출."""
+
+    def __init__(self, file_rel: Path) -> None:
+        self.file_rel = file_rel
+        self.class_stack: list[str] = []
+        self.mapping: dict[str, list[str]] = defaultdict(list)
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        self.class_stack.append(node.name)
+        self.generic_visit(node)
+        self.class_stack.pop()
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        self._maybe_add(node)
+        self.generic_visit(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        self._maybe_add(node)
+        self.generic_visit(node)
+
+    def _maybe_add(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
+        if not node.name.startswith("test_"):
+            return
+        for decorator in node.decorator_list:
+            spec_id = _extract_spec_id(decorator)
+            if spec_id and SPEC_ID_RE.match(spec_id):
+                parts = [*self.class_stack, node.name]
+                self.mapping[spec_id].append(f"{self.file_rel}::{'::'.join(parts)}")
+
+
 def _extract_spec_id(node: ast.AST) -> str | None:
     """``@pytest.mark.spec("vX.Y.Z/...")`` 또는 ``@mark.spec("...")`` 매칭."""
     if not isinstance(node, ast.Call):

scripts/update_upstream_pin.py

@@ -74,7 +74,9 @@ def _previous_pin(pins: dict, current_version: str) -> dict | None:
 
     def key(v: str) -> tuple[int, int, int]:
         m = re.match(r"v(\d+)\.(\d+)\.(\d+)", v)
-        return (int(m.group(1)), int(m.group(2)), int(m.group(3))) if m else (0, 0, 0)
+        if not m:
+            raise ValueError(f"malformed pin key {v!r} — expected vX.Y.Z")
+        return (int(m.group(1)), int(m.group(2)), int(m.group(3)))
 
     target = key(current_version)
     candidates = sorted(