<a id="user-run-wizard"></a>

사용자가 실행하는 설정 안내

<a id="shared-references"></a>

공통 참조

분기 조건에 해당하는 기준을 현재 설치된 소유 스킬에서 읽습니다. 소유 스킬이나 자원이 없거나 일치하지 않으면 해당 행동을 중단합니다. 기억, 다른 설치본이나 승인하지 않은 설치로 대체하지 말고 tk-setup-skills를 사용합니다. 읽기는 워크플로 실행이나 변경 권한을 부여하지 않습니다.

• 사용자 소유 결정·누락된 승인·미충족 선행 조건을 질문이나 질문 도구 입력으로 제시하기 직전에 질문 라운드를 이번 작업에서 읽었는지 확인하고 누락했으면 먼저 읽습니다. 독립적인 결정과 승인은 각각 별도 질문으로 두며, 승인 선택지를 결정 질문에 섞지 않습니다.
• 사용자에게 완료 보고, 산출물 경로 인계나 여러 속성을 비교하는 채팅을 전달하기 전에 채팅 전달을 읽습니다. 작업의 구체적인 출력 계약이 우선합니다.

<a id="ui-evidence"></a>

UI 근거

기존 UI 문구는 언어·대소문자·문장부호·공백을 보존하고 제안 문구와 구분합니다. 근거 없는 탐색 경로를 안내하지 않습니다. UI 문구·경로를 인용·검증·전달할 때 UI 근거를 읽고, 대상에 맞는 근거와 충돌·미확인 사항을 보존합니다. 전달만 하는 분기는 새 조사를 시작하지 않으며, 수집은 담당자의 기존 조사 권한 안에서만 수행합니다. UI와 무관하면 이 참조를 읽지 않습니다.

기본은 사용자가 직접 수행해야 하는 짧은 host-session 대화 안내입니다. 복잡하거나 반복 가능한 사람 수행 절차에서 여러 번의 대화·복사 작업을 줄일 수 있으면 실행형 Wizard를 읽고 검증한 일회성 Bash 스크립트를 제공합니다. 대화 안내를 일괄 교체하거나 일반 CLI 작업을 사용자에게 넘기지 않습니다. 내부적으로 단계, 값의 출처/목적지, 비밀 여부와 안전 경계를 엄격히 추적하되, 이를 승인 문서처럼 사용자에게 쏟아내지 않습니다.

대화는 자연스럽게 진행하고 상태는 엄격하게 관리합니다.

전체 여정을 짧게 개괄한 뒤 사용자가 지금 해야 할 한 가지 행동을 자연스럽게 안내합니다. 이미 완료한 단계를 반복해서 확인하지 않습니다.

<a id="scope"></a>

범위

적용할 수 있는 예시는 다음과 같습니다.

• provisioning과 dashboard 설정입니다.
• credential/secret 값의 발급과 배치입니다.
• login, MFA, OTP, CAPTCHA, passkey입니다.
• permission/keychain/device pairing입니다.
• migration/cutover 중 사람만 수행할 수 있는 단계입니다.
• 호출한 스킬이 안전하게 수행할 수 없는 호스트 설정, 인증, 권한이나 재시작 행동에 대한 정확한 소비자 인계입니다.

agent가 안전하게 실행할 수 있는 일상적인 코드/CLI 작업, 제품 결정과 acceptance verification은 이 스킬의 범위 밖입니다.

다른 스킬이 정확한 설정 인계를 제공하면 소비자 인계를 읽습니다. 호출한 스킬이 자신의 작업과 판정을 계속 담당합니다. 이 안내 스킬은 현재 사람이 수행할 행동과 그 완료 신호만 담당합니다.

<a id="research-and-planning"></a>

조사와 계획

upstream provenance나 adaptation을 결정할 때만 upstream 증류를 읽습니다. 일반적인 wizard 실행 중에는 읽지 않습니다.

먼저 repository와 현재 host evidence를 읽고 다음 내부 상태를 구성합니다.

• 전체 여정과 순서입니다.
• 각 값의 source/destination입니다.
• secret/public 분류입니다.
• 이미 완료한 단계입니다.
• 사용자가 수행해야 할 단계입니다.
• 되돌릴 수 없는 단계입니다.
• 검증할 수 있는 completion signal입니다.

소비자 인계에서는 소비자, 정확한 대기 기준, 감지한 호스트와 기능 상태, 필수 속성과 권장 속성, 재개 행동도 보존합니다. 인계에 이미 있는 값을 사용자에게 다시 말해 달라고 하지 않습니다.

알 수 없는 UI, 버튼, URL이나 명령을 만들지 않습니다. 근거를 이용할 수 없는 지점만 Unverifiable로 설명합니다.

여정이 버전에 민감한 외부 API, OAuth/SSO 제공자나 제공자 대시보드에 의존하고 저장소 근거로 이를 확립할 수 없으면 외부 계약 근거를 읽습니다. 설치된/로컬 계약 근거가 일반적인 최신 문서보다 우선합니다.

제공자 대시보드 탐색을 포함하여 사용자에게 하는 모든 지시에 UI 근거 기준을 적용합니다.

예를 들어 사용자에게 다음과 같이 말합니다.

대략 키 발급 → 로컬 저장 → 연결 확인 세 단계면 끝납니다.
키 값은 대화에 남기지 않을게요. 먼저 발급 화면까지 들어가 주세요.

대화에서는 이전 단계의 completion을 관찰한 뒤에만 다음 단계를 안내합니다. 실행형 경로는 검증된 각 단계의 완료 판정을 스크립트가 수행하고, 에이전트는 전달만으로 완료를 주장하지 않습니다.

<a id="secrets-and-authentication"></a>

비밀과 인증

secret을 echo하거나 chat, Markdown, log, eval에 저장하지 않습니다. 일회성 비밀에는 숨김 입력을 사용합니다. 암호를 포함하여 명시적으로 승인된 개발/QA 애플리케이션 자격 증명은 재사용하거나 정리하기 전에 worktree 로컬 인증을 읽고, 범위가 지정된 보호 파일만 사용합니다. 보존은 새로운 로그인이나 자동 비밀 입력을 승인하지 않습니다.

사용자에게 OTP, password, token, session value나 recovery code를 대화에 붙여 넣으라고 하지 않습니다. 작업에 필요하지 않으면 비밀이 아닌 identifier 값도 보존하지 않습니다.

저장소 작업에서 파일을 통한 입력을 사용하려면 먼저 git ls-files -- .tigerkit/가 추적 경로를 반환하지 않고 git check-ignore -q -- .tigerkit/가 성공한다는 것을 입증합니다. Git에 실제 적용되는 디렉터리별, 로컬 제외 또는 사용자 수준 제외 판정을 받아들입니다. 생성하거나 소비하기 전에 산출물 경로의 사용자 편집 입력 분기를 읽습니다. 상위 작업이 이미 입력 파일을 만들고 보여 주었다면, 정해진 소유자, 수명 주기와 대상 결합을 유지하며 그 정확한 경로를 재사용합니다. 두 번째 wizard 파일을 만들지 않습니다. 이 경계가 없거나 충돌하거나 다른 작업/worktree, 애플리케이션, 검증된 origin, 환경 또는 계정/역할에 속하면 상위 작업이 해결할 때까지 재사용, 덮어쓰기와 삭제를 보류합니다. 새 wizard 소유 입력은 디렉터리 모드 0700, 파일 모드 0600으로 .tigerkit/secret-input/tk-wizard-<run-id>/input.json을 만들고, {"token": ""} 같은 일반 JSON 객체나 정확히 필요한 자격 증명 필드로 초기화합니다. 입력을 기다리기 전에 보고한 경로에 정확한 파일이 여전히 존재하는지 검증하고, 저장소 상대 경로와 절대 경로를 모두 사용자에게 표시합니다. 비밀이 없는 템플릿과 채우고 저장할 필드도 보여 줍니다. 클립보드 명령은 지정한 필드에 JSON 직렬화를 해야 하고 다른 필드를 보존해야 하며, 인수나 셸 이력에 값을 노출하지 않아야 합니다. 값을 수집하려고 편집기, 파일 열기 도구, GUI, 터미널 UI나 포커스를 바꾸는 애플리케이션을 실행하지 않습니다. 경로를 보여 주고 사용자의 명시적인 요청을 받은 뒤에만 파일을 엽니다. 경로가 안전하고 접근 가능하다고 입증할 수 없으면 이용 가능한 호스트 네이티브 숨김 입력을 사용하거나 Blocked | Unverifiable을 반환합니다. 외부 임시 경로로 대체하지 않습니다.

경로를 보여 준 뒤에는 범위를 제한한 메타데이터 변경 폴링을 사용합니다. 비어 있지 않은 초기 템플릿도 여전히 Pending입니다. 변경이 발생하면 신뢰하는 로컬 읽기 도구가 내용이나 파서 발췌를 반환하지 않고 JSON과 모든 필수 필드를 검증합니다. 비어 있거나 누락되거나 일부만 저장된 값은 파일을 다시 쓰지 않은 채 Pending으로 유지합니다. 사용 전에 안전한 경로, 소유권과 모드 0600을 다시 확인하고, 같은 스냅샷을 검증하고 소비한 뒤 완료 메시지 없이 정확한 대기 단계를 계속합니다. 정해진 수명 주기를 적용합니다. 소비한 일회성 비밀 입력과 실행 디렉터리는 성공, 실패나 예외 시 소유자의 정리 권한 안에서만 즉시 제거하고 잔여물이 없는지 검증합니다. 개발/QA 암호를 포함하여 승인되고 범위가 지정된 애플리케이션 인증은 worktree 로컬 인증에 따라 보호 파일을 보존합니다. 단계 완료, 실패, 중단과 접근 만료는 삭제 조건이 아닙니다. 실제 운영 자격 증명, OTP, 복구 코드와 승인 범위 밖의 암호는 계속 일회성 입력으로 취급합니다. 두 실제 경로가 모두 사용자에게 보이는 답변에 나타나기 전에는 사용자 입력 Pending 상태를 반환하지 않습니다. 실제로 만든 파일이 없으면 Blocked | Unverifiable이며, 경로를 추측하라는 지시가 아닙니다. 작업이 활성 상태인 동안 만료된 대기 시간을 갱신합니다. 런타임이 더 이상 기다릴 수 없을 때만 실행 소유 입력 경로를 보존하고 감시 재개 방법을 설명합니다.

helper가 필요하면 일회성 user-run helper로 만들고 다음 의미를 보존합니다.

• 일반 입력과 secret input을 분리합니다.
• 기본적으로 secret 값을 persist하지 않습니다.
• destination을 명확히 보여 줍니다.
• 기존 값을 조용히 덮어쓰지 않습니다.
• bash -n과 가능하면 shellcheck로 정적 검증합니다.
• 이후 삭제하거나 보존하는 방법을 설명합니다.

<a id="-checkpoint---stop--safety-confirmation"></a>

🔴 CHECKPOINT · 🛑 STOP · 안전 확인

아래의 되돌릴 수 없거나 운영에 영향을 주거나 검증할 수 없는 단계는 반드시 중단하는 지점으로 취급합니다. 일반적인 가역적 단계는 불필요한 절차 없이 진행합니다.

일반적인 reversible 단계마다 승인을 요청하지 않습니다. 사용자의 결정을 바꾸거나 되돌리기 어렵거나 production에 영향을 주는 행동에만 명시적 확인을 요구합니다.

예시는 다음과 같습니다.

여기서 기존 production key를 폐기하면 현재 서비스에 영향이 생길 수 있어요.
새 key 연결이 정상인지 먼저 확인한 뒤 폐기하는 걸 권장합니다.
새 key 확인 후 기존 key를 폐기할까요?

안전한 검증 경로가 없으면 실행을 서두르지 않고 Blocked 또는 Unverifiable 상태로 설명합니다.

<a id="completion"></a>

완료

마지막에는 사용자가 무엇을 완료했고 어떻게 검증했는지 짧게 설명합니다. 기본적으로 stage table, secret inventory, 내부 상태 머신이나 긴 receipt를 노출하지 않습니다.

Status: Pass | Pending | Blocked | Unverifiable | Fail 중 실제 상태를 정확히 하나 사용하여 terminal token으로 삼습니다.

<a id="artifact-paths"></a>

산출물 경로

승인된 산출물 쓰기, checkout/전송/제외 설정 또는 임시 입력 소비 전에 산출물 경로를 읽습니다. 안전하고 소유권이 있는 비심볼릭 링크 경로와 Git 제외가 입증된 저장소 임시 공간을 사용합니다. 검사에 실패하면 해당 파일 분기를 중단합니다. 명시적 최종 목적지와 담당자별 기본값을 보존합니다. 미리 채운 입력은 완료한 입력이 아닙니다. 정리 대상은 기록된 리터럴 해석 완료 절대 실행 소유 경로뿐이며, cwd 상대 경로나 glob은 사용하지 않습니다.