@litfamily/litopencode 1.0.0

package/docs/reference-Ko-KR.md

@@ -0,0 +1,309 @@
+# LitOpenCode 워크플로 상세 안내
+
+[빠른 시작](../README-Ko-KR.md) · [English](reference.md)
+
+*워크플로를 한눈에 보면 이렇습니다. 계획은 항목마다 통과/실패가 분명한 검증이 있어야 승인되고, 구현 slice는 실제 surface에서 확인한 evidence와 정리 기록까지 남겨야 닫힙니다. 테스트 통과만으로는 완료가 아닙니다.*
+
+```mermaid
+flowchart TD
+    R["a request<br/>make it better"] --> DI["<b>deep-interview</b><br/>turn it into a decision-complete brief"]
+    DI --> P["<b>lit-plan</b><br/>objective · non-goals<br/>action / output / <b>binary verification</b>"]
+    P --> GATE{"user approves?"}
+    GATE -->|no| P
+    GATE -->|yes| SW["<b>start-work</b><br/>execute one slice"]
+
+    subgraph LOOP["each slice: RED to GREEN to SURFACE to CLEAN"]
+        SW --> RED["failing test first"]
+        RED --> GREEN["smallest change that passes"]
+        GREEN --> SURF["exercise the <b>real surface</b><br/>not just the test"]
+        SURF --> CLEAN["tear down · cleanup receipt"]
+    end
+
+    CLEAN --> EV{"evidence complete?"}
+    EV -->|"tests only"| SW
+    EV -->|"artifact + receipt"| RW["<b>review-work</b><br/>scope · evidence · payload<br/>security · real surface"]
+    RW -->|findings| SW
+    RW -->|clean| HO["<b>lit-handoff</b><br/>resumable packet"]
+
+    style GATE fill:#fff3cd,stroke:#856404
+    style EV fill:#fff3cd,stroke:#856404
+    style SURF fill:#d4edda,stroke:#155724
+    style RW fill:#d1ecf1,stroke:#0c5460
+```
+
+## 설치
+
+권장 설치:
+
+scoped 패키지가 npm 설치 대상입니다. [패키지 이전 안내](migration.md#scoped-npm-package-migration)를 확인하세요.
+
+```sh
+npm exec --package @litfamily/litopencode@latest -- litopencode install
+```
+
+설정 변경을 미리 보거나 설치 상태를 확인할 수 있습니다.
+
+```sh
+npm exec --package @litfamily/litopencode@latest -- litopencode install --dry-run
+npm exec --package @litfamily/litopencode@latest -- litopencode doctor
+```
+
+설치 명령은 OpenCode의 plugin installer를 통해 플러그인을 등록합니다.
+`~/.config/opencode/litopencode.json`이 없을 때만 route 파일을 만들고, 기존 route는
+그대로 둡니다. 기본 OpenCode 설정 파일은 `~/.config/opencode/opencode.jsonc`입니다.
+`XDG_CONFIG_HOME`이 설정되어 있으면 `$XDG_CONFIG_HOME/opencode/opencode.jsonc`를 사용합니다.
+
+*OpenCode의 이벤트가 플러그인으로 들어오면 TypeScript runtime이 route와 권한 경계를 적용하고, tool guard와 durable ledger로 결과를 남깁니다. 아래 흐름이 설치 후 실제로 연결되는 host surface입니다.*
+
+```mermaid
+flowchart LR
+    subgraph OC["OpenCode"]
+        E1["chat.message"]; E2["command.execute.before"]
+        E3["tool.execute.before"]; E4["tool.execute.after"]; E5["event"]
+    end
+    subgraph LO["LitOpenCode plugin"]
+        RT["TypeScript runtime<br/>routing · bounded authority"]
+        GUARD["tool guards"]
+        LEDGER[("durable ledger")]
+    end
+    E1 --> RT; E2 --> RT; E3 --> GUARD; E4 --> GUARD; E5 --> RT
+    RT --> LEDGER; GUARD --> LEDGER
+    LO --> S["41 skills"]
+```
+
+권한과 모델은 명시적으로 선택합니다.
+
+```sh
+npm exec --package @litfamily/litopencode@latest -- litopencode install --permission-prompt
+npm exec --package @litfamily/litopencode@latest -- litopencode install --permission-mode balanced
+npm exec --package @litfamily/litopencode@latest -- litopencode install --yolo
+npm exec --package @litfamily/litopencode@latest -- litopencode install --provider openai --model gpt-6-astra --effort xhigh
+npm exec --package @litfamily/litopencode@latest -- litopencode install --provider openai --model gpt-5.6-luna --effort max
+```
+
+기본값은 safe/ask-first입니다. `balanced`와 `yolo`는 선택했을 때만 적용됩니다.
+`install --yes`는 모든 선택 메뉴를 건너뛰고 저장된 출력 스타일을 유지합니다.
+CI와 비대화형 터미널에서는 자동 질문을 생략하며, 명시한 질문 플래그는 계속 동작합니다.
+`NO_COLOR`에서도 출력 스타일을 직접 선택할 수 있지만 색상·커서 이스케이프는 출력하지
+않습니다. `TERM=dumb`이나 UTF-8이 아닌 로케일에서는 ANSI 장식 없이 `LIT` 문자를 표시합니다.
+새로 설치하거나 초기화하면 계획·검토 및 `lit-loop`는 `openai/gpt-6-astra`/`xhigh`,
+실행·연구 helper는 기존 `openai/gpt-5.6-luna`/`max`를 사용합니다. Astra는 low/medium/high/
+xhigh/max를 지원하며 native reasoning effort로 전달됩니다. 기존 helper 선택, provider/model
+필드, `momus`·`litwork-reviewer` 재정의는 덮어쓰지 않습니다. 기존 GPT-5.6 계열의 `-fast`
+의미는 유지하지만 `gpt-6-astra-fast` 별칭은 추가하지 않습니다.
+전역 설치가 필요하면 다음을 사용합니다.
+
+```sh
+npm install -g @litfamily/litopencode
+litopencode install
+```
+
+## 처음 사용하기
+
+설치 후 OpenCode를 재시작하고 Tab을 누르세요. agent 선택기에 다음 세 agent가 보여야 합니다.
+
+| Agent | 역할 |
+| --- | --- |
+| `lit-loop` | 구현, 검증, 안전한 위임, 진행 기록 |
+| `lit-plan` | 근거가 있는 계획 작성. `edit`, `bash`, `task` 권한은 허용하지 않음 |
+| `lit-implement` | `/start-work` 이후 승인된 계획 실행 |
+
+작업 순서는 다음과 같습니다.
+
+1. `lit-plan`에 하나의 범위가 분명한 계획을 요청합니다.
+2. 계획을 승인한 뒤 `/start-work`를 실행합니다.
+3. 완료를 주장하기 전에 `/review-work`를 실행합니다.
+
+## 주요 명령
+
+| 경로 | 용도 |
+| --- | --- |
+| `/lit` | 일반 `lit-loop` 워크플로 시작 |
+| `/litwork` | 제한된 작업 루프 진입 |
+| `/lit-plan` | 읽기 전용 구현 계획 작성 |
+| `/start-work` | 승인된 계획을 `lit-implement`로 실행 |
+| `/review-work` | 초안 계획 또는 완료 작업 검토 |
+| `/litresearch` 또는 `/lit-research` | 순차 대체 경로를 포함한 근거 기반 연구 |
+| `/lit-handoff` | 이어서 작업할 수 있는 핸드오프 작성 |
+| `/lit-recap` | 로컬 ledger와 세션 맥락으로 짧은 리캡 작성 |
+| `/lit-scientific-visualization` | 패키지에 포함된 scientific-visualization 워크플로 사용 |
+| `/lit-korean` | 의미를 바꾸지 않고 문장 흐름 검토 |
+| `/text-neutralization` | neutralization 계약에 따른 문장 검토 |
+
+그 밖에 `/refactor`, `/lit-burnoff`, `/lit-code`, `/debugging`, `/lit-commit`,
+`/lsp`, `/lsp-setup`, `/rules`, `/deep-interview`, `/structural-search`,
+`/autoresearch`, `/autoconference`, `/wikify-*` 경로가 있습니다. 이 경로는 안내 또는 제한된
+로컬 동작을 추가합니다. 호스트 권한은 늘리지 않습니다.
+
+### Durable loop 상태
+
+LitOpenCode는 `.litopencode/litgoal/lit-loop/`에 goal 상태를 저장합니다. append-only
+ledger에 진행 상황과 evidence를 기록합니다.
+
+```sh
+litopencode status
+litopencode create-goals --session-id <id> --objective <text>
+litopencode record-evidence --criterion-id <id> --kind <red|green|scenario|cleanup|note> --ref <ref>
+litopencode checkpoint --summary <text>
+litopencode complete-goals
+```
+
+`/start-work init|resume|cancel|complete|status <schema-3 JSON>`은 승인된 실행을 위한
+bounded-authority 경로입니다. `resume`은 신뢰된 사용자 경로와 work, session, revision,
+grant가 모두 맞을 때만 허용됩니다. 복사하거나 인용한 텍스트는 명령으로 처리하지 않습니다.
+
+### UI 및 Visual QA 관리 헬퍼
+
+`frontend-ui-ux`와 `visual-qa` 경로는 Node ESM 헬퍼와 제한된 읽기 전용
+evidence를 사용합니다. 이 경로들은 workflow family의 scaffold나 status
+헬퍼를 추가하지 않습니다.
+
+### 관리되는 workflow family
+
+Autoresearch와 Autoconference가 제한된 로컬 workflow를 위한 scaffold/status
+헬퍼를 제공합니다. Wikify는 템플릿과 contract를 소유하지만 scaffold나
+status helper는 제공하지 않습니다. Wikify probe는
+`tool.execute.after`, `chat.message`, `command.execute.before`를 포함한
+다섯 개 surface를 확인하며, 나머지 host hook surface는 Wikify contract에
+기록되어 있습니다. Wikify는 `tool.execute.after`에서 하나의 제한된
+`wikify` tool도 소유하고, Autoresearch나 Autoconference tool은 노출하지
+않습니다.
+
+## Release Readiness
+
+출시 담당자는 [`release-checklist.md`](release-checklist.md)를
+사용합니다. 이 문서는 현재 설치 동작만 설명합니다.
+
+## 검증
+
+LitOpenCode checkout에서 다음 검사를 실행합니다.
+
+```sh
+npm install
+npm run build
+npm test
+npm run typecheck
+npm run check:managed-skill-manifest
+npm run scan:legacy-tokens
+npm run check:version
+npm run check:pack-payload
+npm run qa:real-surface
+npm pack --dry-run --json --ignore-scripts
+```
+
+쓰기 없는 로컬 probe:
+
+```sh
+node bin/litopencode.cjs doctor --root .
+node bin/litopencode.cjs install --dry-run --root .
+```
+
+`doctor`는 package, route, command, skill, 로컬 상태를 쓰기 없이 확인합니다.
+
+*패키지에 소스 파일이 있다는 사실만으로는 충분하지 않습니다. `npm pack` 결과 안에서 skill이 선언한 참조가 모두 해소되어야, 아무것도 없는 새 머신에서도 설치 후 동작한다고 말할 수 있습니다.*
+
+```mermaid
+flowchart LR
+    SK["a skill"] --> Q{"does it declare<br/>a capability?"}
+    Q -->|"self-contained<br/>procedure"| AL["explicit allowlist entry<br/>with a written reason"]
+    Q -->|"needs a corpus"| C["corpus must resolve<br/>inside the <b>packed payload</b>"]
+    AL --> G1
+    C --> G1["<b>payload-substance</b>"]
+    G1 --> G2["<b>cross-product parity</b><br/>one product cannot ship a stub<br/>where the family ships substance"]
+    G2 --> G3["<b>referenced-path resolution</b><br/>every path in a SKILL.md<br/>must exist in the tarball"]
+    G3 --> OK["installs and works<br/>on a machine that has<br/>nothing else"]
+    style C fill:#d4edda,stroke:#155724
+    style OK fill:#d4edda,stroke:#155724
+```
+
+## 제거
+
+`uninstall` 서브커맨드는 없습니다. 전역 설치를 했다면 먼저 npm 패키지를 제거합니다.
+
+```sh
+npm uninstall -g @litfamily/litopencode
+```
+
+그 다음 OpenCode가 관리하는 `opencode.jsonc`(또는 custom root의 `opencode.json`)의
+`plugin` 배열에서 `@litfamily/litopencode` 또는 `@litfamily/litopencode@<version>` 항목을 제거합니다.
+더 이상 route가 필요하지 않을 때만 `~/.config/opencode/litopencode.json`을 제거하세요.
+프로젝트의 `.litopencode/`는 별도 ledger와 receipt입니다. 나중에 재개할 계획이 없다면
+그 상태를 버려도 되는지 확인한 뒤 직접 정리합니다.
+
+## 안전과 업데이트
+
+- `lit-plan`은 계획 전용입니다. `edit`, `bash`, `task` 권한을 허용하지 않습니다.
+- `balanced`와 `yolo`는 선택형 권한 모드입니다. `balanced`에서는 위험한 shell 패턴이
+  계속 ask로 남고, `yolo`도 planner의 deny guard와 하위 agent 재귀 위임을 풀지 않습니다.
+- 패키지 시작과 대화형 `install`/`doctor` 성공 뒤에는 정확한 버전을 확인하는 foreground
+  update barrier가 동작합니다. `--no-auto-update` 또는 `LITOPENCODE_NO_AUTO_UPDATE=1`로
+  끌 수 있습니다. cache-only 알림은 `NO_UPDATE_NOTIFIER=1` 또는
+  `LITOPENCODE_NO_UPDATE_CHECK=1`로 끌 수 있습니다.
+- Public-source retrieval에는 SSRF 검사, redirect 검증, byte 제한, access verdict가
+  있습니다. 가져온 본문은 명령이 아니라 데이터로 처리합니다.
+
+## 패키지 경로
+
+- 패키지와 plugin id: `litopencode`
+- CLI binary: `litopencode`
+- 공개 export: `litopencode`, `litopencode/server`
+- 전역 route 파일: `~/.config/opencode/litopencode.json`
+- 프로젝트 override: `.litopencode/config.json`
+- Durable 상태: `.litopencode/litgoal/`
+- 사용자 상태 루트: `~/.litopencode/`
+
+## 스킬 이름 변경
+
+새 명령은 `/lit-crucible`, `/lit-init`, `/lit-commit`, `/lit-burnoff`, `/lit-burnoff-file`,
+`/lit-korean`, `/lit-fetch`, `/lit-code`입니다. 이전 이름은 한 릴리스 동안 새 명령으로
+연결되며, 이름 변경 안내가 한 줄 표시됩니다. 다음 마이너 버전에서 이전 이름을 제거합니다.
+설치·업데이트는 새 복사본을 검증한 뒤 설치 도구가 관리하는 이전 이름의 스킬 디렉터리를
+제거합니다. 사용자 소유 파일은 보존합니다. 자세한 내용은 [마이그레이션 안내](migration.md#skill-id-renames)를 참고하세요.
+
+## 문서
+
+- [빠른 시작](../README-Ko-KR.md)
+- [English reference](reference.md)
+- [Changelog](../CHANGELOG.md)
+- [마이그레이션](migration.md)
+- [터미널 마크](lit-mark.md)
+- [출시 담당자 체크리스트](release-checklist.md)
+
+
+## 설치된 원본 스킬 파일
+
+`lit-handoff`와 `lit-scientific-visualization`의 원본은 선택한 OpenCode 설정 루트의
+`skills/<id>/canonical/`에 그대로 설치합니다. 먼저 native 스킬의 `SKILL.md`를 읽고,
+그 파일의 디렉토리를 기준으로 `exact_source_root`를 해석하세요. 슬래시 명령과
+bare 경로도 같은 native 스킬 위치를 사용합니다. 프로젝트나 command 디렉토리를
+기준으로 원본을 찾으면 안 됩니다. 패키지 설치에는 참조 파일 전체가 포함되며
+개발자의 checkout이 필요하지 않습니다.
+
+Doctor는 패키지 원본뿐 아니라 설치된 파일 목록과 해시도 확인합니다. Python이나
+matplotlib이 없는 `DEGRADED` 상태와 설치 파일 누락은 별개입니다. 파일 누락은
+무결성 오류이며, 어느 검사도 의존성을 자동으로 설치하지 않습니다.
+
+재설치할 때 생성 표시가 없는 사용자 스킬은 보존합니다. 생성된 wrapper의 새
+canonical 하위 트리는 패키지의 파일 목록과 해시가 일치할 때만 교체합니다.
+수정·추가·누락된 파일이나 심볼릭 링크가 있으면 거부합니다. 변경한 파일은 관리
+트리 밖에 백업한 뒤 다시 시도하세요. 이 하위 트리가 없는 이전 flat wrapper에는
+누락된 원본을 추가할 수 있습니다. 기존에 생성된 wrapper와 배포 파일은 계속
+설치 도구의 관리 대상이므로 교체될 수 있습니다. 모든 생성 파일의 편집 내용을
+보존한다는 뜻은 아닙니다.
+
+
+과학 스킬의 Python 모듈을 일반적으로 import하면 `__pycache__` 파일이 생길 수
+있습니다. Doctor는 해당 경로를 `canonicalCacheFiles`에 표시합니다. 정상 파일인
+CPython/PyPy 태그의 `.pyc`(최적화 태그 포함)가 해시가 그대로인 관리 대상 `.py`에
+대응하는지 확인하며, 바이트코드를 실행하거나 그 내용을 신뢰하지 않습니다.
+그 밖의 추가 파일, 원본 누락·수정, 파일이나 디렉토리의 심볼릭 링크는 계속 거부합니다.
+
+캐시가 생긴 상태에서 재설치하면 이전 스킬 트리 전체를 native 스킬 탐색 범위 밖인
+`<config-root>/.litopencode-canonical-backups/<unique-id>/skill`에 보관합니다.
+`prepared.json`은 이동 전 기록이고 `receipt.json`은 보관 완료 기록과 캐시별
+SHA-256을 담습니다. 실제로 사용할 위치에는 원본을 새로 복사하므로 보관한
+바이트코드가 새 원본보다 먼저 실행되지 않습니다. 캐시 없는 재설치와 이전 flat
+wrapper 이전에는 보관 사본이 필요하지 않습니다. 교체나 안전한 복귀가 실패하면
+안내된 복구 경로를 보존하고 확인하세요. 설치 성공으로 간주하면 안 됩니다.
+이 검사는 일반적인 사용과 감지한 경로 변경을 다루며, 적대적인 동시 파일 변경까지
+막는다는 보장은 아닙니다.