ff-lntools 0.1.0__py3-none-any.whl

ff_lntools-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: ff-lntools
+Version: 0.1.0
+Summary: ln-structure checker, blast radius, doc generator and Claude Code hooks
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# ff-lntools
+
+ln-structure 프로젝트용 정적 검사, 영향 범위, 문서 생성 도구와 Claude Code 훅.
+표준 라이브러리만 사용. Python 3.10+.
+
+ln-structure 규칙: `src/lntools/protocol/for-agent-codingprotocol-ln-structure.md`
+
+## 설치
+
+```
+pip install git+https://github.com/gatesplan/ff-lntools
+```
+
+프로젝트가 쓰는 Python 환경마다 설치한다. 훅이 `python -m lntools` 로 호출하기 때문이다.
+
+## 프로젝트 세팅
+
+```
+lnt init --skill    # 1회. ~/.claude/skills/init-protocol 스킬 설치
+cd my-project
+lnt init            # .claude/ 에 프로토콜 문서 복사, CLAUDE.md 생성, 훅 병합
+```
+
+Claude Code 에서는 `/init-protocol` 이 같은 일을 한다. 코딩 프로토콜 문서의 원본은 이 저장소의
+`src/lntools/protocol/` 이다.
+
+## 명령
+
+```
+lnt init [--skill]          # 프로젝트에 코딩 프로토콜 설치
+lnt check [--file PATH]     # C1 방향, C2 표면, C3 층 일치, C4 순환. 위반 시 exit 1
+lnt blast MODULE [-d N]     # MODULE 변경 시 영향받는 상위 모듈. 인터페이스 상속 경유 포함
+lnt map                     # 모듈 목록, 층, 의존
+lnt doc                     # for-agent-layerinfo.md, for-agent-layerinfo-lN.md 생성
+lnt doc --check             # 생성 결과와 파일 비교. 다르면 exit 1
+lnt doc --stamp MODULE      # for-agent-moduleinfo.md 의 sources hash 갱신
+lnt move MODULE lK          # 모듈을 lK 로 이동. 패키지/tests 의 import 재작성, tests 미러 이동,
+                            # 두 층의 __init__ 을 지연 re-export 로 재생성, 문서 재생성
+lnt hook post-edit          # Claude Code PostToolUse 훅 진입 (stdin JSON)
+lnt hook session-start      # Claude Code SessionStart 훅 진입
+```
+
+`--root` 로 프로젝트 안의 아무 경로를 주면 `src/<pkg>/lN` 을 찾아 올라간다. 기본은 현재 디렉토리.
+
+## 검사 규칙
+
+| 코드 | 내용 |
+|---|---|
+| C1 | import 대상 층이 자기 층보다 낮아야 한다. 같은 층도 위반. `TYPE_CHECKING` 안의 import 도 포함 |
+| C2 | `pkg.lN.module` 표면까지만 import. 모듈 안의 파일이나 중첩 모듈 내부로 진입 금지 |
+| C3 | 선언 층 == 계산 층 (의존 최고 층 + 1, 의존 없으면 0, 외부 패키지 의존이 있으면 최소 1) |
+| C4 | 모듈 간 runtime import 순환 금지. 모듈 내부 파일 간 순환은 규칙 밖 |
+
+## Claude Code 훅
+
+`.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "matcher": "startup|resume|clear|compact",
+      "hooks": [{"type": "command", "command": "python -m lntools hook session-start"}]
+    }],
+    "PostToolUse": [{
+      "matcher": "Edit|Write|MultiEdit",
+      "hooks": [{"type": "command", "command": "python -m lntools hook post-edit", "timeout": 30}]
+    }]
+  }
+}
+```
+
+- session-start: `src/<pkg>/for-agent-layerinfo.md` 를 세션 컨텍스트에 주입
+- post-edit: 편집한 파일이 `src/**/*.py` 이면 그 모듈을 검사.
+  위반은 exit 2 + stderr 로 에이전트에게 오류로 전달되고, 위반이 없으면 영향 범위와
+  문서 stale 여부가 additionalContext 로 전달된다
+
+## 문서
+
+- `for-agent-layerinfo.md` (패키지 루트, 중첩 모듈 루트): 층별 모듈 목록. 마커 사이는 생성, 한 줄 설명과 마커 밖은 보존
+- `for-agent-layerinfo-lN.md` (각 층): 공개 클래스 메서드 시그니처. 마커 사이는 생성
+- `for-agent-moduleinfo.md` (각 모듈): 사람이 쓴다. `sources` 헤더의 hash 로 stale 판정만 한다

ff_lntools-0.1.0.dist-info/RECORD

@@ -0,0 +1,59 @@
+ff_lntools-0.1.0.dist-info/licenses/LICENSE,sha256=a866MbOAIcwhnga_SLR_8hE05-WvYEX9qe0LtzvRRz4,1066
+lntools/__init__.py,sha256=wTPp70LSqWgaaxvgMwXikmDCca5IHyznb9tuPGs0cW8,45
+lntools/__main__.py,sha256=FF98yEbkB4qjdp92eaJvYyidRIwsHbGKoykm6aHVzZk,55
+lntools/for-agent-layerinfo.md,sha256=f3KGiuifgpG9hQSYHcW15uYbZlhFNs69ATPo5o7dbAw,1586
+lntools/l0/__init__.py,sha256=Be6sqCdKBx6GOnuhBl-8WFMP-7canS_fCNac921110Q,604
+lntools/l0/for-agent-layerinfo-l0.md,sha256=k03FwR9Wa90HlQXYH8ay5hPiMsKNNAHxYYN_BZEXdcc,1438
+lntools/l0/edge/__init__.py,sha256=oiCQq3R7F3bnqhmhLmGlFej0tgnVNDjlM8aIYfuJOtY,43
+lntools/l0/edge/edge.py,sha256=UB7l6iY4fRsRKFUbN1s2_79_ImjcToKOSUlg2_24JHw,899
+lntools/l0/initializer/__init__.py,sha256=SESnsQJRm6OftZw5NZMMBXGM25rg2tlGcYlz2jzvs9I,98
+lntools/l0/initializer/initializer.py,sha256=7ff8XAlVHft_HHYNrv9X7js2MTojn_Au3R8cM7GIqws,2783
+lntools/l0/module_ref/__init__.py,sha256=vNBbuQGlrdzqAf8wkXDQS-J6fFk9YfHNZuaExBHoRSg,59
+lntools/l0/module_ref/module_ref.py,sha256=80UOnYZ_7uMV_M7n-E_jtfS0SbTjtoF4ptqHVNQV0_I,1087
+lntools/l0/project_layout/__init__.py,sha256=JWo1s5Ek6p9Mlr2CXI9vBDOB1XNc42Y3HuLZVynvBI0,93
+lntools/l0/project_layout/project_layout.py,sha256=OnB9DhRBdX1y_12out3XKOo_tRLhtS2kCwzhYMu8f9Q,1671
+lntools/l0/raw_import/__init__.py,sha256=_YRv7q5MjAK1CIQrh-AjSEJDwbDLlAiTfN0keDTXtBM,59
+lntools/l0/raw_import/raw_import.py,sha256=Q23ByMoqgwgkm9eJhtuB1OSqG-6t8Xp80UPJXeMKwJc,513
+lntools/l0/signature_extractor/__init__.py,sha256=LUdwTprOBBpCT_gvsF4yiEucU8p6DnQPqhs2YCOgncE,86
+lntools/l0/signature_extractor/signature_extractor.py,sha256=kEmQnvCM4mKHvg4QKcab96OqaNJZd0xutPb2vCu5Bew,3547
+lntools/l0/violation/__init__.py,sha256=G5CCgjVc6ZAhtXLK7y2Rvejw8pcPpgTT-MxFzTxmIKI,58
+lntools/l0/violation/violation.py,sha256=QktjTT4bK-Be0xEawegt_j8WvzfynsWe1FL3VngIAyw,609
+lntools/l1/__init__.py,sha256=1uzHtjv2arjz5hDmJ7gV9GGcVXqMt6XXdXgZI2VkyV0,340
+lntools/l1/for-agent-layerinfo-l1.md,sha256=o5-U6Ns5mhDTVLuL2NJAgH4ZbJQmiIsldd-OUCaUpi8,1017
+lntools/l1/graph/__init__.py,sha256=IiYvwf3SFD6a8CM-EuVPf-ljAAQp-iFyjIx3bMxvuAs,46
+lntools/l1/graph/graph.py,sha256=ZQw2dpd2Q1BQZ04VUuloeGMC31X1bzyvyyhik5AUZZ0,3844
+lntools/l1/layer_init_writer/__init__.py,sha256=6e_pTnEi-Kd1L2HwBlAp1vlwXo4fbZUYopQ24TKVSwM,78
+lntools/l1/layer_init_writer/layer_init_writer.py,sha256=1rCvEtRPqKbowPVhAwlwzOaaEwxZehQWWf-XxjsQgEc,1214
+lntools/l1/scanner/__init__.py,sha256=JMVLGeXHlkuCciQ-Mi32Zp1C-WvOzVQgue--6anpOz4,52
+lntools/l1/scanner/scanner.py,sha256=viqZQCnKzU2OSutLGMKqHWPadaMLnPjK82cd4KS68pw,9107
+lntools/l2/__init__.py,sha256=8Xp6tLsvyH3k-_2B3wtIrVBSjGW_r_Ucf_X1d6bKVeg,337
+lntools/l2/for-agent-layerinfo-l2.md,sha256=mWUHkWXnNN4Zu6m9KeGZZkimy_erfsuzgmiv9gkQDWE,1409
+lntools/l2/blaster/__init__.py,sha256=wt8eYYTMTjJ1Ip1IBSD_MeAdjL3-7DpgR5b7GwDuzX8,52
+lntools/l2/blaster/blaster.py,sha256=hk32__9AcGEf6FLytWb1iRIBms4258uCaks0rlc8KHg,812
+lntools/l2/checker/__init__.py,sha256=gLr_3IVhANcZIuhdEm4LEKH34fpAJLoM6YNseBw8mCg,52
+lntools/l2/checker/checker.py,sha256=KdCXxKI-umzqGW-weQbCyVuRlENjZBO26bCTAQUXMYM,1955
+lntools/l2/doc_generator/__init__.py,sha256=rdXXqge7PIBm5aDrPv7tdcZS85wZ2DXMvItbFu5Vfn4,68
+lntools/l2/doc_generator/doc_generator.py,sha256=VLVqU1yIanHDyJ5_8mCYaqsl0f3B4DXcXQrIotOqqI4,8899
+lntools/l3/__init__.py,sha256=lfxGqNpG2WTaFKor5BCuCY-__Zxlk3_W2rB-AcasuMQ,303
+lntools/l3/for-agent-layerinfo-l3.md,sha256=wIIrIzbapV0h2foZrSaBVStzrUuXOQ_OqebN6R56QI4,409
+lntools/l3/hook_runner/__init__.py,sha256=d7czPFX_eITQeKwYTS3XwMiba8CwvElBelKzY-Vdkl0,62
+lntools/l3/hook_runner/hook_runner.py,sha256=clfYcSMupGmpnvR-NPe_sD8VELYcGtrtiVOp6YtMy6g,2839
+lntools/l3/mover/__init__.py,sha256=fWMZu5zVpQR_o4bPy2_DZmjokOXJguZK7miXZU-4NhI,46
+lntools/l3/mover/mover.py,sha256=j37O5xXRl_mIW7SHCnfRKasn5NKewyyoJDqZPXPSeq0,8035
+lntools/l4/__init__.py,sha256=fKrHbvAcQmjfJTkOVx6CwBv9YUwvhRqP5fnUjcO8dCY,285
+lntools/l4/for-agent-layerinfo-l4.md,sha256=S299PDuKfdxdSe6Y_enCOWagEgSEHAHbh2XeZoGyvCw,209
+lntools/l4/cli/__init__.py,sha256=5QEV2-vr3YIUyICon_fYBCK1ohgJQbMGRWx3Ca74uFk,54
+lntools/l4/cli/cli.py,sha256=tmfm-0nGChOEnOGIDju1YGIuPURgsTqzp8b6QkyxV8I,5479
+lntools/protocol/CLAUDE-template.md,sha256=i2c9RO9lfD6ih_ncPXilHlXdI2jYputhpWC-39euo5I,537
+lntools/protocol/SKILL-template.md,sha256=rm0UxGTpZhGT-czGCuLPu4hcKaNEU8SnCno9h6M26lg,1053
+lntools/protocol/for-agent-codingprotocol-ln-structure.md,sha256=JCMIHF-7-W1lob-nxlso5sJ1Cqe-E_b4Ir4NPq4pUdg,11152
+lntools/protocol/for-agent-codingprotocol-python.md,sha256=14u_vIK0JV6hDIEs100Wqu9KpurlQKVjh5FxGFn8LCk,2378
+lntools/protocol/for-agent-layerinfo-ln-template.md,sha256=Oteao1f_KaXrX0cJO7zK6Oz7Hi0PMOWaGDT3e9m03cI,3284
+lntools/protocol/for-agent-layerinfo-template.md,sha256=ukn8rzubQ4AC1mwBMCbfmbd5B-dKPtcCWn_3sb6sgII,1296
+lntools/protocol/for-agent-moduleinfo-template.md,sha256=hPhNOHeGMtI2q5YewwFf5ANyCuZsaRbL-0Op5pBUjZ0,2814
+lntools/protocol/settings-hooks-template.json,sha256=rbZrBQ-xmAqpAgOH8mLlYppJKae1xnoM4WMoHHcLdks,434
+ff_lntools-0.1.0.dist-info/METADATA,sha256=JS34FGxN9Nr_Wh1rvApoI9nWLB1JmHqOilJOQ6t4BWI,3961
+ff_lntools-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ff_lntools-0.1.0.dist-info/entry_points.txt,sha256=Z5E1LExTtwFPTIAbGOOJPX4carO2wItrcKzdJrqV90M,44
+ff_lntools-0.1.0.dist-info/top_level.txt,sha256=gSjFhkTIgi4WVkojB2fhnSpncploMRdDg7AxiIDsJ60,8
+ff_lntools-0.1.0.dist-info/RECORD,,

ff_lntools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ff_lntools-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lnt = lntools.l4.cli:main

ff_lntools-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gatesplan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ff_lntools-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+lntools

lntools/__init__.py

@@ -0,0 +1,3 @@
+from .l4.cli import main
+
+__all__ = ["main"]

lntools/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .l4.cli import main
+
+sys.exit(main())

lntools/for-agent-layerinfo.md

@@ -0,0 +1,33 @@
+# for-agent-layerinfo.md
+
+<!-- lnt:generated:start -->
+## l0
+- edge: 모듈 간 의존 간선. kind runtime/type_only/inherits, 표면 초과 경로 extra
+- initializer: lnt init. 프로토콜 문서 복사, CLAUDE.md, 훅 병합, 스킬 설치
+- module_ref: ln 모듈 하나. 이름, 스코프, 선언 층, 파일 목록, 외부 의존 여부
+- project_layout: 프로젝트 루트와 src/<pkg> 탐색. LAYER_RE
+- raw_import: 해석 전 import 문 하나. target, names, kind, external
+- signature_extractor: 모듈 __init__ 공개 이름과 클래스 메서드 시그니처를 ast 로 추출
+- violation: 규칙 위반 C1~C4 레코드와 포맷
+
+## l1
+- graph: 모듈 그래프. 계산 층, 역의존, 인터페이스 경유 blast, 순환 탐지
+- layer_init_writer: 층 __init__.py 를 PEP 562 지연 re-export 형태로 생성
+- scanner: src/<pkg> 를 훑어 모듈과 간선 생성. 상대/절대/층 단위 import 해석, TYPE_CHECKING 구분
+
+## l2
+- blaster: blast 결과 텍스트 보고서
+- checker: C1 방향, C2 표면, C3 층 일치, C4 순환 검사
+- doc_generator: layerinfo/layerinfo-ln 생성과 검사, moduleinfo sources hash stamp/stale
+
+## l3
+- hook_runner: Claude Code 훅 진입. stdin JSON 해석, exit 2 / additionalContext 채널 선택
+- mover: lnt move. 모듈 층 이동, import 재작성, tests 미러, 층 __init__ 와 문서 재생성
+
+## l4
+- cli: lnt 명령줄. check, blast, map, doc, hook
+<!-- lnt:generated:end -->
+
+## Notes
+
+의존은 항상 아래로만. l4 cli 가 진입점이며 모든 하위를 조립한다.

lntools/l0/__init__.py

@@ -0,0 +1,22 @@
+import importlib
+
+# 공개 이름 -> 모듈 폴더명. 지연 로드
+_EXPORTS = {
+    "Edge": "edge",
+    "Initializer": "initializer",
+    "LAYER_RE": "project_layout",
+    "PROTOCOL_FILES": "initializer",
+    "ModuleRef": "module_ref",
+    "ProjectLayout": "project_layout",
+    "RawImport": "raw_import",
+    "SignatureExtractor": "signature_extractor",
+    "Violation": "violation",
+}
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str):
+    if name in _EXPORTS:
+        mod = importlib.import_module(f".{_EXPORTS[name]}", __name__)
+        return getattr(mod, name)
+    raise AttributeError(name)

lntools/l0/edge/__init__.py

@@ -0,0 +1,3 @@
+from .edge import Edge
+
+__all__ = ["Edge"]

lntools/l0/edge/edge.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+
+# 모듈 간 의존 간선. import 문 하나가 간선 하나
+@dataclass
+class Edge:
+    src: str              # 출발 모듈 이름
+    dst: str | None       # 도착 모듈 이름. 층 단위 import에서 이름을 못 풀면 None
+    dst_layer: int        # 도착 층 번호
+    kind: str             # runtime | type_only | inherits
+    file: Path            # import 문이 있는 파일
+    line: int
+    target: str           # import 문에 쓰인 점 경로 (패키지명 제외)
+    extra: str = ""       # 도착 모듈 표면을 지나 들어간 나머지 경로. 비어있지 않으면 표면 위반
+
+    @property
+    def counts_for_layer(self) -> bool:
+        # 층 계산에 포함되는 간선. 상속 간선은 이미 runtime 간선이 따로 있으므로 제외
+        return self.kind in ("runtime", "type_only")

lntools/l0/for-agent-layerinfo-l0.md

@@ -0,0 +1,40 @@
+# l0
+
+<!-- lnt:generated:start -->
+## edge
+Edge.counts_for_layer() -> bool  # edge.py
+
+## initializer
+Initializer.__init__(project_root: Path, home: Path | None=None)  # initializer.py
+Initializer.run() -> list[str]  # initializer.py
+Initializer.merge_hooks() -> str  # initializer.py
+Initializer.install_skill() -> Path  # initializer.py
+PROTOCOL_FILES  # 정의를 찾지 못함
+
+## module_ref
+ModuleRef.basename() -> str  # module_ref.py
+ModuleRef.layer_name() -> str  # module_ref.py
+ModuleRef.contains(other: str) -> bool  # module_ref.py
+
+## project_layout
+ProjectLayout.__init__(project_root: Path, package_root: Path)  # project_layout.py
+ProjectLayout.package_name() -> str  # project_layout.py
+ProjectLayout.src_dir() -> Path  # project_layout.py
+ProjectLayout.has_layers(d: Path) -> bool  # project_layout.py
+ProjectLayout.find(start: Path) -> 'ProjectLayout | None'  # project_layout.py
+ProjectLayout.relative(path: Path) -> str  # project_layout.py
+LAYER_RE  # 정의를 찾지 못함
+
+## raw_import
+RawImport  # raw_import.py (공개 메서드 없음)
+
+## signature_extractor
+SignatureExtractor.exports_of(module_dir: Path) -> list[str]  # signature_extractor.py
+SignatureExtractor.extract(module_dir: Path, exported: list[str]) -> list[str]  # signature_extractor.py
+
+## violation
+Violation.format(base: Path | None=None) -> str  # violation.py
+<!-- lnt:generated:end -->
+
+## Notes
+

lntools/l0/initializer/__init__.py

@@ -0,0 +1,3 @@
+from .initializer import Initializer, PROTOCOL_FILES
+
+__all__ = ["Initializer", "PROTOCOL_FILES"]

lntools/l0/initializer/initializer.py

@@ -0,0 +1,63 @@
+import json
+from importlib import resources
+from pathlib import Path
+
+PROTOCOL_FILES = [
+    "for-agent-codingprotocol-ln-structure.md",
+    "for-agent-codingprotocol-python.md",
+    "for-agent-layerinfo-template.md",
+    "for-agent-layerinfo-ln-template.md",
+    "for-agent-moduleinfo-template.md",
+]
+
+
+# 프로젝트에 코딩 프로토콜을 설치한다. 문서 복사, CLAUDE.md, 훅 병합, 스킬 설치
+class Initializer:
+    def __init__(self, project_root: Path, home: Path | None = None):
+        self.project_root = project_root
+        self.home = home if home is not None else Path.home()
+        self.claude_dir = project_root / ".claude"
+
+    @staticmethod
+    def _protocol(name: str) -> str:
+        return (resources.files("lntools") / "protocol" / name).read_text(encoding="utf-8")
+
+    # 반환: 한 일의 설명 줄 목록
+    def run(self) -> list[str]:
+        done: list[str] = []
+        self.claude_dir.mkdir(parents=True, exist_ok=True)
+        for name in PROTOCOL_FILES:
+            (self.claude_dir / name).write_text(self._protocol(name), encoding="utf-8")
+            done.append(f".claude/{name}")
+        claude_md = self.project_root / "CLAUDE.md"
+        if claude_md.is_file():
+            done.append("CLAUDE.md 이미 존재 (건너뜀)")
+        else:
+            claude_md.write_text(self._protocol("CLAUDE-template.md"), encoding="utf-8")
+            done.append("CLAUDE.md 생성")
+        done.append(self.merge_hooks())
+        return done
+
+    # settings.json 의 hooks 에 템플릿 훅을 합친다. 같은 command 가 이미 있으면 건너뛴다
+    def merge_hooks(self) -> str:
+        tpl = json.loads(self._protocol("settings-hooks-template.json"))
+        dst = self.claude_dir / "settings.json"
+        cur = json.loads(dst.read_text(encoding="utf-8")) if dst.is_file() else {}
+        hooks = cur.setdefault("hooks", {})
+        added = 0
+        for event, groups in tpl["hooks"].items():
+            existing = hooks.setdefault(event, [])
+            have = {h.get("command") for g in existing for h in g.get("hooks", [])}
+            for g in groups:
+                if not any(h.get("command") in have for h in g["hooks"]):
+                    existing.append(g)
+                    added += 1
+        dst.write_text(json.dumps(cur, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        return f".claude/settings.json 훅 {added}개 추가" if added else ".claude/settings.json 훅 이미 있음"
+
+    # ~/.claude/skills/init-protocol/SKILL.md 설치
+    def install_skill(self) -> Path:
+        p = self.home / ".claude" / "skills" / "init-protocol" / "SKILL.md"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(self._protocol("SKILL-template.md"), encoding="utf-8")
+        return p

lntools/l0/module_ref/__init__.py

@@ -0,0 +1,3 @@
+from .module_ref import ModuleRef
+
+__all__ = ["ModuleRef"]

lntools/l0/module_ref/module_ref.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+# ln-structure 모듈 하나. 이름은 패키지 루트 기준 점 경로 (예: l1.order, l3.portfolio.l1.store)
+@dataclass
+class ModuleRef:
+    name: str
+    scope: str            # 소속 스코프. 루트는 "", 중첩 모듈 내부는 감싸는 모듈 이름
+    layer: int            # 선언 층 (디렉토리 번호)
+    path: Path            # 모듈 디렉토리
+    files: list[Path] = field(default_factory=list)   # 모듈에 속한 모든 .py (중첩 내부 포함)
+    has_external: bool = False                         # 표준 라이브러리 외 패키지 import 여부
+    is_nested: bool = False                            # 내부에 lN 디렉토리를 가지는지
+
+    @property
+    def basename(self) -> str:
+        return self.name.rsplit(".", 1)[-1]
+
+    @property
+    def layer_name(self) -> str:
+        # 소속 층의 이름. 예: l1, l3.portfolio.l1
+        return self.name.rsplit(".", 1)[0]
+
+    def contains(self, other: str) -> bool:
+        return other.startswith(self.name + ".")

lntools/l0/project_layout/__init__.py

@@ -0,0 +1,3 @@
+from .project_layout import ProjectLayout, LAYER_RE
+
+__all__ = ["ProjectLayout", "LAYER_RE"]

lntools/l0/project_layout/project_layout.py

@@ -0,0 +1,51 @@
+import re
+from pathlib import Path
+
+LAYER_RE = re.compile(r"^l(\d+)$")
+
+
+# 프로젝트 루트와 패키지 루트(src/<pkg>) 위치
+class ProjectLayout:
+    def __init__(self, project_root: Path, package_root: Path):
+        self.project_root = project_root.resolve()
+        self.package_root = package_root.resolve()
+
+    @property
+    def package_name(self) -> str:
+        return self.package_root.name
+
+    @property
+    def src_dir(self) -> Path:
+        return self.package_root.parent
+
+    @staticmethod
+    def has_layers(d: Path) -> bool:
+        if not d.is_dir():
+            return False
+        return any(c.is_dir() and LAYER_RE.match(c.name) for c in d.iterdir())
+
+    # start(파일 또는 디렉토리)에서 위로 올라가며 src/<pkg>/lN 을 가진 프로젝트를 찾는다
+    @classmethod
+    def find(cls, start: Path) -> "ProjectLayout | None":
+        start = start.resolve()
+        if start.is_file():
+            start = start.parent
+        for p in [start, *start.parents]:
+            src = p / "src"
+            if not src.is_dir():
+                continue
+            candidates = [c for c in sorted(src.iterdir()) if cls.has_layers(c)]
+            if not candidates:
+                continue
+            # 시작 위치를 포함하는 패키지 우선
+            for c in candidates:
+                if start == c or c in start.parents:
+                    return cls(p, c)
+            return cls(p, candidates[0])
+        return None
+
+    def relative(self, path: Path) -> str:
+        try:
+            return path.resolve().relative_to(self.project_root).as_posix()
+        except ValueError:
+            return path.as_posix()

lntools/l0/raw_import/__init__.py

@@ -0,0 +1,3 @@
+from .raw_import import RawImport
+
+__all__ = ["RawImport"]

lntools/l0/raw_import/raw_import.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+
+# 파일 하나에서 뽑은 import 문 하나. 아직 모듈로 해석되기 전 상태
+@dataclass
+class RawImport:
+    target: str | None       # 패키지명을 포함한 절대 점 경로. None: 패키지 밖이거나 해석 불가
+    names: list[str]         # from X import a, b 의 a, b. import X 면 빈 목록
+    kind: str                # runtime | type_only | inherits
+    line: int
+    external: bool = False   # 표준 라이브러리가 아닌 외부 패키지

lntools/l0/signature_extractor/__init__.py

@@ -0,0 +1,3 @@
+from .signature_extractor import SignatureExtractor
+
+__all__ = ["SignatureExtractor"]

lntools/l0/signature_extractor/signature_extractor.py

@@ -0,0 +1,78 @@
+import ast
+from pathlib import Path
+
+
+# 모듈 디렉토리에서 공개 이름과 그 시그니처를 ast로 뽑는다
+class SignatureExtractor:
+    # 모듈 __init__.py의 공개 이름. __all__ 우선, 없으면 from .x import Y 의 Y
+    def exports_of(self, module_dir: Path) -> list[str]:
+        init = module_dir / "__init__.py"
+        if not init.is_file():
+            return []
+        tree = ast.parse(init.read_text(encoding="utf-8"), filename=str(init))
+        names: list[str] = []
+        for node in tree.body:
+            if isinstance(node, ast.Assign):
+                for t in node.targets:
+                    if isinstance(t, ast.Name) and t.id == "__all__":
+                        return [e.value for e in getattr(node.value, "elts", []) if isinstance(e, ast.Constant) and isinstance(e.value, str)]
+            if isinstance(node, ast.ImportFrom) and node.level >= 1:
+                names.extend(a.asname or a.name for a in node.names)
+        return names
+
+    # 공개 이름 각각의 시그니처 줄. 클래스는 Class.method(...) -> ret, 함수는 name(...) -> ret
+    # 각 줄 끝에 정의가 있는 파일을 모듈 디렉토리 기준으로 붙인다
+    def extract(self, module_dir: Path, exported: list[str]) -> list[str]:
+        defs = self._collect_defs(module_dir)
+        lines: list[str] = []
+        for name in exported:
+            found = defs.get(name)
+            if found is None:
+                lines.append(f"{name}  # 정의를 찾지 못함")
+                continue
+            node, rel = found
+            if isinstance(node, ast.ClassDef):
+                lines.extend(self._class_lines(node, rel))
+            else:
+                lines.append(self._func_line(node, prefix="", drop_self=False, rel=rel))
+        return lines
+
+    def _collect_defs(self, module_dir: Path) -> dict[str, tuple[ast.AST, str]]:
+        defs: dict[str, tuple[ast.AST, str]] = {}
+        for f in sorted(module_dir.rglob("*.py")):
+            if f.name == "__init__.py":
+                continue
+            try:
+                tree = ast.parse(f.read_text(encoding="utf-8"), filename=str(f))
+            except SyntaxError:
+                continue
+            rel = f.relative_to(module_dir).as_posix()
+            for node in tree.body:
+                if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+                    defs.setdefault(node.name, (node, rel))
+        return defs
+
+    def _class_lines(self, cls: ast.ClassDef, rel: str) -> list[str]:
+        out: list[str] = []
+        for node in cls.body:
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            if node.name.startswith("_") and node.name != "__init__":
+                continue
+            out.append(self._func_line(node, prefix=cls.name + ".", drop_self=True, rel=rel))
+        if not out:
+            out.append(f"{cls.name}  # {rel} (공개 메서드 없음)")
+        return out
+
+    def _func_line(self, fn: ast.AST, prefix: str, drop_self: bool, rel: str = "") -> str:
+        args = ast.unparse(fn.args)
+        if drop_self:
+            if args == "self" or args == "cls":
+                args = ""
+            elif args.startswith("self, "):
+                args = args[6:]
+            elif args.startswith("cls, "):
+                args = args[5:]
+        ret = f" -> {ast.unparse(fn.returns)}" if fn.returns is not None else ""
+        where = f"  # {rel}" if rel else ""
+        return f"{prefix}{fn.name}({args}){ret}{where}"

lntools/l0/violation/__init__.py

@@ -0,0 +1,3 @@
+from .violation import Violation
+
+__all__ = ["Violation"]

lntools/l0/violation/violation.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+
+# 규칙 위반 하나. code는 C1(방향) C2(표면) C3(층 일치) C4(순환)
+@dataclass
+class Violation:
+    code: str
+    module: str
+    file: Path
+    line: int
+    message: str
+
+    def format(self, base: Path | None = None) -> str:
+        p = self.file
+        if base is not None:
+            try:
+                p = p.relative_to(base)
+            except ValueError:
+                pass
+        loc = f"{p.as_posix()}:{self.line}" if self.line > 0 else p.as_posix()
+        return f"[{self.code}] {self.module} ({loc}) {self.message}"

lntools/l1/__init__.py

@@ -0,0 +1,15 @@
+import importlib
+
+_EXPORTS = {
+    "Graph": "graph",
+    "LayerInitWriter": "layer_init_writer",
+    "Scanner": "scanner",
+}
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str):
+    if name in _EXPORTS:
+        mod = importlib.import_module(f".{_EXPORTS[name]}", __name__)
+        return getattr(mod, name)
+    raise AttributeError(name)

lntools/l1/for-agent-layerinfo-l1.md

@@ -0,0 +1,25 @@
+# l1
+
+<!-- lnt:generated:start -->
+## graph
+Graph.__init__(modules: dict[str, ModuleRef], edges: list[Edge])  # graph.py
+Graph.modules_of(file: Path) -> list[ModuleRef]  # graph.py
+Graph.dependencies(name: str) -> list[Edge]  # graph.py
+Graph.dependents(name: str, kinds: tuple[str, ...]=('runtime', 'type_only')) -> list[str]  # graph.py
+Graph.interfaces_of(name: str) -> list[str]  # graph.py
+Graph.computed_layer(name: str) -> int  # graph.py
+Graph.blast(name: str, depth: int=1) -> list[tuple[str, str]]  # graph.py
+Graph.cycles() -> list[list[str]]  # graph.py
+
+## layer_init_writer
+LayerInitWriter.__init__()  # layer_init_writer.py
+LayerInitWriter.render(modules: list[ModuleRef]) -> str  # layer_init_writer.py
+LayerInitWriter.write(layer_dir: Path, modules: list[ModuleRef]) -> Path  # layer_init_writer.py
+
+## scanner
+Scanner.__init__(layout: ProjectLayout)  # scanner.py
+Scanner.scan() -> tuple[dict[str, ModuleRef], list[Edge]]  # scanner.py
+<!-- lnt:generated:end -->
+
+## Notes
+