inkcheck

** ink 스토리를 위한 기계적 QA.** 컴파일 검사, 제한된 체계적 분기 탐색, 런타임 오류 재현 경로, 그리고 죽은 콘텐츠 탐지 — 작가와 팀을 위한 독립형 CLI로 제공되며, 선택적으로 CI 및 MCP 통합을 지원합니다.

에이전트는 여기서 시작하세요 → SKILL.md — 이 도구를 호출해야 하는 시점, 작업 예시, MUST/MUST NOT. 계열 계약: FAMILY.md.

inkcheck은 QA 도구이지 집필 도구가 아닙니다. 산문 한 단어도 생성하거나, 다시 쓰거나, 외부로 보내지 않습니다. inkcheck의 존재 목적은 당신이 쓴 스토리를 기계적으로 검사할 수 있게 하는 것입니다: ink의 공식 컴파일러로 컴파일하고, 명시적 한도 내에서 선택 경로를 탐색하며, 플레이어가 발견하기 전에 실패를 재현합니다.

AI를 사용하나요?

아니요. inkcheck 자체는 스토리를 테스트하기 위해 AI, 머신러닝, LLM 또는 생성 모델을 사용하지 않습니다. 소스를 학습하거나, 산문 변경을 추론하거나, 스토리 텍스트를 다시 쓰거나, 스토리 콘텐츠를 AI 서비스로 보내지 않습니다.

이 도구는 인간, CI 시스템, 그리고 선택적 AI 코딩 에이전트가 모두 동일한 기계적 QA 검사를 실행할 수 있도록 설계되었습니다. 실제 검사는 결정적 코드로 수행됩니다: 공식 ink 컴파일러, ink 런타임, 제한된 분기 탐색, 그리고 구조화된 보고서입니다.

Related MCP server: RenForge MCP

2분 만에 사용해 보기

Node.js 18 이상 필요:

npx -y inkcheck path/to/main.ink

자신의 스토리를 시도하기 전에 실패 경로 보고서를 보고 싶으신가요? 2분 합성 데모를 실행해 보세요.

제품 약속

inkcheck은 ink 스토리를 위한 제한된 기계적 QA입니다. 대규모 스토리의 모든 경로가 작동한다는 것을 증명하지는 않습니다. 명시적 한도 내에서 도달 가능한 스토리 상태를 결정적으로 탐색하고, 발견한 문제에 대한 정확한 재현 경로를 보고하며, 커버리지가 부분적이었던 위치와 이유를 보여줌으로써, 작가가 저렴하고 반복 가능한 회귀 보험으로 사용할 수 있게 합니다.

inkcheck은 대규모 인터랙티브 스토리에 버그가 없다는 것을 증명하지 않습니다. 조합적 폭발은 현실입니다: 루프, 변수, 무작위성, 호스트 게임 코드는 어떤 도구도 완전히 방문할 수 없는 수보다 더 많은 가능한 상태를 만들어낼 수 있습니다.

약속은 더 좁고 더 유용합니다: 기계적 스토리 QA를 저렴하고, 반복 가능하며, 실행 가능하게 만드는 것입니다. inkcheck은 명시적 한도 내에서 실제 도달 가능한 선택 상태를 탐색하고, 실행이 부분적이었을 때 이를 알려주며, 실패를 수정 후 다시 실행할 수 있는 재현 경로로 전환합니다. 오늘 깨진 경로를 찾았다면, 동일하게 구성된 검사는 내일도 그 경로를 다시 찾을 수 있어야 합니다.

이것이 오픈소스 QA 프로젝트인 이유는 그 경계가 중요하기 때문입니다. 보고서가 과장되었거나, 명백한 패턴을 놓쳤거나, 더 나은 탐색 전략이 필요하거나, 안전하게 공유할 수 있는 스토리 형태에서 실패한다면, 픽스처나 이슈를 가져와 주세요. 로드맵의 목표는 부분 커버리지를 더 투명하고 더 가치 있게 만드는 것이지, 부분 커버리지가 증명이 된다고 가장하는 것이 아닙니다.

제품 방향 및 자체 점수

inkcheck의 미래 가치는 재현 가능한 하이브리드에서 나올 것으로 계획되어 있습니다: 광범위한 시드 프로브, 체계적인 로컬 검사, 제한된 다양성 탐색, 그리고 게이트, 루프, 어서션, 스토리렛 자격을 위한 Ink 인식 전문가입니다. 전문가는 제한된 상태를 유지해야 하며 포트폴리오-신규 증거를 통해 더 많은 작업을 얻어야 합니다. 전문가도 예산 트랩이 될 수 있기 때문입니다.

동일한 조건이 하드웨어에도 적용됩니다. 로컬 CLI와 일회성 MCP 포트폴리오 검사는 기본적으로 결정적 1,024-상태 라이브 파일럿을 사용하며, 이는 소규모, 깊이-제한, 저자-프론티어-포화 작업을 순차적으로 유지하고 지속적인 공개 프론티어가 있을 때만 제한된 워커를 활성화합니다. 모든 파일럿 상태는 원래의 전체 상한에 포함됩니다. 결정을 내리기 위해 탐색이 재시작되지는 않습니다. 매칭 평가는 정확한 증거를 유지했으며 5M-상태 깊이-100 The Intercept 실행을 25.6% 개선했지만, 제한된 작업과 호스팅 작업은 명시적 순차 상한을 유지합니다. 동시성 평가를 참조하세요.

이들은 평균이 아닌 개별 점수입니다. 높은 신뢰 점수는 놓친 런타임 오류를 상쇄할 수 없습니다. 상세한 제품 및 엔지니어링 진실 점수카드는 각 10/10 목표, 현재 증거, 엔지니어링 제약, 그리고 각 에픽 또는 릴리스에서 사용되는 재평가 프로토콜을 정의합니다. 첫 번째 완전한 정책 v2 승격 평가는 혼합 증거를 출시 주장으로 전환하지 않고 동적 할당을 실험적 상태로 유지합니다.

Inkcheck 0.6 범위

Inkcheck 0.6은 보편적으로 더 나은 동적 검색 정책을 주장하지 않고 언제든지 QA 기반을 제공합니다. 기존의 제한된 포트폴리오가 검색 기본값으로 유지됩니다. 워크로드 인식 동시성은 라이브 파일럿이 충분한 지속 작업을 보여줄 때 결과를 왼쪽으로 이동시킬 수 있습니다. 지속적인 캠페인은 돌아와서 재개하고 소스-결과 창을 검사할 수 있습니다. 인간과 에이전트는 명명된 시간/리소스 포지션을 선택할 수 있습니다. 모든 자동 결정은 귀속 가능합니다. 롱테일 확장, 순환, 중지는 세 계열 승격 게이트가 작가 대상 가치를 충분히 입증하지 못했기 때문에 섀도 전용으로 유지됩니다.

이것은 완료된 릴리스 계약이지, 더 큰 연구 문제가 해결되었다는 주장이 아닙니다. 동적 첫 창 크기 조정, 컴팩트 대형 체크포인트, 제공자 귀속 비용, 더 넓은 에이전트 평가, 제한된 전문가 탐색기는 별도로 추적되는 로드맵 작업으로 남아 있습니다. 미래 릴리스는 검사된 증거가 동일한 중요 보존, 재실행, 리소스, 정직성 게이트를 통과한 후에만 고정 포트폴리오를 대체할 수 있습니다.

Inkcheck 0.7: 중요한 규칙

Inkcheck 0.7은 작성자 선언 불변식을 로컬 구성, CI, MCP뿐만 아니라 호스팅 검사기에서도 일급 기능으로 만듭니다. 작가는 웹 흐름에서 gold >= 0과 같은 선택적 숫자 규칙 하나를 추가할 수 있습니다. 이는 실행 전에 일반 언어와 생성된 타입 구성으로 표시되고, 일반적인 제한된 QA 중에 검사되며, 위반 시 정확한 재실행 증인과 함께 보고됩니다. 웹 흐름은 선언된 Ink 변수를 감지하여 선택을 돕지만 서버는 권위를 유지합니다: 알 수 없는 변수, 잘못된 타입, 지원되지 않는 문법은 탐색 전에 실패합니다. 임시 규칙 구성은 업로드와 함께 삭제됩니다. 에이전트는 타입이 지정된 규칙 제안을 초안할 수 있지만 조용히 승인할 수는 없습니다. 버전 0.7.2는 또한 비공개 QA 증거 핀을 추가합니다: 승인된 런타임, 어서션 또는 목표 증인은 편집 후 추가 탐색 없이 재검사할 수 있지만, 광범위한 검증을 위해서는 새로운 제한 실행이 여전히 필요합니다.

별도의 어서션-지시 전문가는 여전히 옵트인 및 실험적 상태입니다. 기본 예산을 받지 않으며, 점수카드를 변경하지 않으며, 사전 등록된 증거 게이트를 통과하기 전까지 더 나은 커버리지를 주장하지 않습니다. 중요한 규칙 계약은 두 경계를 모두 정의합니다.

에이전트 캠페인 정책

MCP 에이전트는 탐색기 가중치를 직접 만들지 않고 quick, balanced, deep, overnight, 또는 campaign 모드와 같은 높은 수준의 모드로 지속적인 캠페인을 시작할 수 있습니다. balanced는 신규 에이전트 기본값입니다. fixed는 명시적 레거시 제어를 보존합니다. 제한된 오버라이드는 상태/창/시간/메모리/디스크/마감 포지션, 부족/균형/풍부 리소스, 선호 가치(broad_qa, runtime_assertions, outcomes, 또는 approved_goals), 보호된 롱테일 작업, ceilings 대 knee 중지를 변경할 수 있습니다. 정확한 기본 창은 어서션/목표 없이 유지되며 재개 가능합니다. 보호된 롱테일 할당은 이제 대체 검색 시드와 더 깊은 바운드로 결정적 루트-시작 포트폴리오 자식을 시작하면서 정확한 기본 체크포인트를 보존합니다. runtime_assertions 캠페인은 add_assertions로 검증된 어서션 창을 추가할 수 있습니다. approved_goals 캠페인은 add_goal로 검증된 목표를 추가할 수 있습니다. 모든 자식은 명시적 승인을 사용하고, 별도의 증거 보고서를 저장하며, 캠페인-신규 중요, 의도, 저자-매듭 또는 터미널 증거에 대해서만 크레딧을 받습니다.

첫 번째 저자-스토리 캠페인-자식 평가는 The Intercept에서 하나의 그럴듯한 오래된-변수 검토 리드와 하나의 기각된 어서션 가설을 발견했습니다. 단계적 목표는 실패했고, 두 고예산 자식 모두 5M 전에 메모리에서 중지되었으며, 500K 공유 기본은 지속 체크포인트 상한을 초과했습니다. 이는 유망한 어서션 가치와 함께 명확한 경고입니다: 에이전트가 작성한 규칙은 인간 검증이 필요하고, 전문가는 프로브-대-확장 경제학이 필요하며, 대규모 캠페인이 일상화되기 전에 컴팩트 체크포인트가 필요합니다.

매칭된 독립 롱테일 평가는 보호된 루트-시작 포트폴리오 파티션과 성장하는 공유 프론티어를 비교했습니다. 5M Intercept 캠페인에서 공유 암은 786,559 총 상태에서 메모리로 중지되었습니다. 9개의 독립 자식은 더 낮은 최고 힙에서 5M 전체를 완료했고 407 대비 3,558개의 캠페인-신규 터미널 변형을 크레딧했습니다. 새로운 중요 이슈, 저자 매듭 또는 가시적 엔딩은 발견되지 않았습니다. 이는 보편적 QA 가치 주장이 아닌, 리소스 효율적 다양성과 측정 가능한 수확 체감에 대한 증거입니다.

이후의 세 계열 0.6 승격 게이트는 동적 중지 또는 확장을 승격하지 않았습니다. Dog Ink Adventure와 Heresy II 모두 500K 기본이 재개 가능한 체크포인트를 생성하기 전에 리소스 상한에 도달했으므로 어떤 롱테일 정책도 작동할 수 없었습니다. The Intercept에서 독립 파티션은 1.40 GiB 최고 힙에서 4.66M 상태에 도달한 반면, 성장하는 프론티어는 3.70 GiB에서 787K 상태로 중지되었습니다. 터미널 재발견은 34%에서 94%로 상승했으며, 새로운 중요 이슈, 저자 매듭 또는 가시적 결과는 없었습니다. inkcheck은 이러한 권장 사항을 섀도 전용으로 유지하고 동적 첫 창 크기 조정을 더 강력한 다음 제품 요구 사항으로 취급합니다.

모든 결과 창은 안정적인 정책 ID, 할당 이유, 측정된 선호 수율, 처리량/리소스 증거, 다른 창에 대한 불확실성-라벨링된 경험적 범위, 모든 바인딩 제약, 그리고 전체 곡선이나 발견을 검사하는 데 사용되는 보고서 ID를 반환합니다. 컴팩트 검사는 또한 최신 창의 목적, 파티션, 한계 수율을 명명합니다. Knee는 선호 수율이 없는 연속 3개 창을 요구하며 보호된 프로브를 소비할 수 없습니다. 이는 실제로 실행된 궤적에 대한 제한된 관찰로 유지되며, 스토리가 커버되었다거나 이후 발견이 존재하지 않는다는 주장이 아닙니다. 캠페인 정책 계약 및 MCP 결과 창 가이드를 참조하세요.

After independent children run, the compact decision also includes a versioned shadow-only long-tail recommendation: expand the same family, rotate to another partition, or stop after the protected floor. It uses campaign-new value under the selected preference, reports recent yield per state and second, requires progressively more dry probes for scarce/balanced/abundant postures, and exposes compact selected-value rediscovery plus factual report-local discovery gaps. Older ledgers mark those signals unavailable. Rediscovery is identity overlap with earlier campaign reports, not raw duplicate-state work; widening gaps are observations, not plateau proof. liveEffect: false means this evidence cannot change allocation yet.

Humans can use the same durable policy without learning its controls: inkcheck campaign story.ink runs the balanced intent, while --mode quick, deep, or overnight chooses an outcome-and-time posture. It returns immutable source-bound result windows as work progresses, preserves the latest partial report on a deadline or cancellation between windows, and keeps technical state/time/memory/disk ceilings available as expert overrides. Result windows separate work spent, actionable yield, forecast uncertainty, and whether search can continue. A quiet discovery interval or observed knee is never described as complete coverage.

Quick start

Node.js 18 이상에서:

npx -y inkcheck path/to/main.ink

전역 설치가 필요하지 않습니다. 첫 실행은 고정된 공식 ink 컴파일러를 다운로드하고 SHA-256 해시를 검증한 다음 스토리를 로컬에서 처리합니다.

프로젝트 구성

프로젝트가 모든 인간 또는 에이전트 세션에 동일한 진입점과 제한된 CI 설정을 사용해야 하는 경우 inkcheck.yml을 커밋하세요:

schemaVersion: 1
entrypoint: story.ink
ci:
  maxDepth: 100
  maxStates: 1000000
  goalMaxStates: 250000
  seed: 1
  storySeed: 1
  search: portfolio
  concurrency: auto
  strict: true
assertions:
  - id: gold_nonnegative
    description: Gold never goes negative
    when: always
    condition:
      left: { variable: gold }
      operator: ">="
      right: { literal: 0 }
goals:
  - id: depleted_gold
    description: Seek paths where the player runs out of gold
    condition:
      left: { variable: gold }
      operator: "<="
      right: { literal: 0 }

확인하려면 inkcheck validate-config를 실행하세요. 해당 디렉터리에서 inkcheck는 구성된 진입점과 기본값을 사용합니다. 명시적 CLI 플래그가 여전히 우선합니다. 알 수 없는 키는 검증에 실패하므로 지원되지 않는 외부 동작 및 편집 정책 필드가 구현된 것처럼 보일 수 없습니다. 게시된 계약은 config schema v1입니다.

어서션은 타입이 있는 데이터이며, JavaScript나 임의의 Ink 표현식이 아닙니다. 피연산자는 변수 또는 스칼라 리터럴입니다. 비교는 ==, !=, <, <=, >, >=를 사용하고, 조건은 all, any, not으로 구성할 수 있습니다. 규칙은 항상, 터미널 상태에서, 또는 명명된 knot에 진입할 때 실행됩니다. 알 수 없는 변수/knot 및 잘못된 교차 타입 비교는 탐색이 상태 예산을 소비하기 전에 실패합니다. 위반은 항상 CI를 실패시키고 관찰된 값과 정확한 인덱싱된 재현 증인을 포함합니다. 제한된 정상 실행은 단지 "위반이 관찰되지 않음"만을 의미하며, 오직 완전 실행만 규칙을 완전히 검증된 것으로 보고합니다.

목표는 동일한 비실행 조건 문법을 사용하지만 CI를 실패시키는 대신 탐색을 안내합니다. 일반 탐색은 항상 전체 maxStates 예산을 받습니다. 구성에서 goalMaxStates를 설정하거나 CLI에서 --goal-states를 사용하여 명시적 결정적 목표-근접 슬라이스를 추가할 수 있습니다. 기본값은 0이며 결합 예산은 100,000,000 상태를 초과할 수 없습니다. 추가 슬라이스가 요청되지 않은 경우에도 일반 탐색 중에 목표는 여전히 관찰됩니다. 도달한 목표에는 정확한 선택 인덱스가 포함됩니다. 미달은 완전 탐색이 실제로 도달 불가능함을 증명하지 않는 한 not_reached_within_limits를 반환합니다. 보고서는 기준, 목표, 총 예산을 별도로 노출하므로 스티어링이 일반 QA 결과를 조용히 대체할 수 없습니다. search experiments의 비교 증거를 참조하세요.

후기 복합 종속성의 경우 condition을 두 개 이상의 순서가 있는 stages로 대체하세요. 각 단계는 동일한 타입 문법을 사용합니다. Inkcheck는 첫 번째로 충족되지 않은 누적 마일스톤을 찾으므로, 이후 단계는 상태가 이전 모든 단계도 충족하는 경로에서만 도달합니다. 충족되지 않은 선행 조건이 있으면 이후 단계는 blocked_by_stage로 남습니다. 이를 도달 불가능하다고 부르지 않습니다. 이 첫 번째 단계별 계약은 하나의 공유 추가 목표 예산을 사용하고 런타임 체크포인트를 직렬화하는 대신 스토리 루트에서 결정적으로 재시작합니다.

.ink 파일 하나를 포함하는 새 프로젝트의 경우 inkcheck init이 이 구성을 만듭니다. 다중 파일 프로젝트는 --entrypoint로 루트를 지정해야 합니다. inkcheck agent-kit --format codex는 필요할 때 구성, 고정된 GitHub Actions 예제, .inkcheck/ 아티팩트 무시 규칙, 그리고 컴팩트한 버전 일치 에이전트 지침을 추가합니다. 두 명령 모두 멱등적이며 모든 대상을 사전 점검합니다. 기존 작성 파일을 덮어쓰거나 부분 수정하는 대신 전체 작업을 거부합니다. npm 아티팩트에는 표준 skills/inkcheck/SKILL.md, 점진적 Ink/워크플로 참조, 10개의 실행 가능한 골든 연습문제도 포함됩니다. inkcheck capabilities --json은 이를 features.bundledAgentSkill로 광고하며 설치된 스키마 계약에 대한 권위로 남습니다.

--save-report는 버전이 지정된 보고서를 .inkcheck/reports/ 아래에 원자적으로 저장하고 콘텐츠 및 진입점에서 파생된 안정적인 ID를 반환합니다. 이후 세션에서 inkcheck artifacts list --json과 inkcheck artifacts show <report-id> --json을 사용할 수 있습니다. 다시 열면 저장된 증거가 현재 진입점에 대해 current, stale 또는 path_changed인지 보고합니다. 보고서에는 스토리 텍스트, 변수, 정확한 증인이 포함될 수 있으므로 에이전트 키트는 기본적으로 이를 무시합니다. 신뢰, 개인정보 보호, 호환성 계약은 local report artifacts를 참조하세요.

긴 base-shared 실행은 정확한 라이브 프런티어를 로컬에 영속화할 수도 있습니다. --search=shared --no-min-repro --save-checkpoint로 시작한 다음 나중에 inkcheck resume <checkpoint-id> --max-states N으로 계속하세요. N은 더 큰 총 허용량이지 숨겨진 추가 작업이 아닙니다. inkcheck checkpoints list/show는 제한된 메타데이터, 영속적인 압축 크기, 저장소 인코딩, 소스 신선도를 보고합니다. 새 체크포인트 파일은 스트리밍 gzip 아티팩트입니다. 이전의 일반 schema-v1 JSON은 계속 읽을 수 있습니다. 체크포인트는 비공개, 원자적, 소스/구성 바인딩, 기본 무시, 보존 상한이 적용됩니다. 작성된 텍스트와 런타임 상태를 포함할 수 있습니다. local resumable checkpoints를 참조하세요. MCP 에이전트는 내구성 있는 start_search / inspect_search / continue_search / cancel_search 결과 창을 통해 동일한 정확한 기반을 사용할 수 있습니다. 또한 add_goal을 사용하여 스토리 루트에서 시작하고 해당 정확한 기본 프런티어를 건드리지 않는 명시적 추가 지시 프로브를 추가할 수 있습니다. 포트폴리오, 공유 변수, 어서션, 지시 프런티어 재개, 호스팅 작업은 아직 이 체크포인트 계약을 사용하지 않습니다.

호스팅 검사기

저장소에는 이제 터미널을 사용하고 싶지 않은 작성자를 위한 자체 호스팅 웹 인터페이스가 포함됩니다. 호스팅 모드는 승인된 .ink 소스를 일시적으로 업로드하고, Quick(더 이른 250K 상태 결과) 및 Balanced(더 깊은 1M 상태 결과) 의도를 제공하며, 단기 비공개 작업을 생성하고, 실제 작업, 수익, 불확실성 신호를 스트리밍하며, 완료, 취소 또는 실패 후 임시 작업 디렉터리를 삭제합니다. 완료된 호스팅 검사는 소스-바운드 결과-창 정체성과 안정적인 발견 ID를 반환합니다. 보고서를 공개하지 않으며 애플리케이션 로그에 스토리 텍스트를 보존하지 않습니다. 선택적 퍼스트파티 사용량 메트릭은 일일 집계 수와 개인정보 보호를 유지하는 대략적인 일일 고유 브라우저 추정치를 유지합니다. IP, 사용자 에이전트, 브라우저 토큰, 방문자 프로필은 보존되지 않습니다.

로컬 CLI는 스토리 업로드가 발생하지 않으므로 개인정보 보호 우선 옵션으로 남습니다. 위협 모델, Docker 배포, 운영 한계, 현재 월 50달러 미만 예산은 Hosted checker deployment를 참조하세요.

무엇을 잡아내는가

• 컴파일 오류 및 경고 — 깨진 divert, 해결되지 않은 변수, 마무리되지 않은 끝, 파일 및 줄 번호 포함 (inklecate, 공식 컴파일러를 통해)

• 재현 경로가 있는 런타임 오류 — 0으로 나누기, 잘못된 외부 호출 또는 콘텐츠 이탈을 유발하는 정확한 선택 시퀀스 (예: repro: [Enter in darkness → Descend to the cellar])

• 종료되지 않을 수 있는 강제 선택 순환 — 유일한 선택지가 동일한 작성자-가시 변수와 함께 동일한 제어 상태로 돌아갈 때 보수적 검토 경고. 선택적 출구, 무작위 동작, 턴 수, 방문 수, EXTERNAL 호출은 의도적으로 제외됩니다.

• 방문되지 않은 콘텐츠, 분류됨 — 구성된 한도 내에서 어떤 탐색 경로도 방문하지 않는 knot. 각각 인바운드 divert 스캔으로 분류: "여기에는 작성된 divert 지점이 없음 — 고아일 가능성" 대 "인바운드 divert가 있음 — 이번 실행 한도를 초과했을 가능성"

• 고유한 터미널 상태 — 각각에 도달하는 선택 트레일 포함. 서로 다른 최종 변수는 별개의 결과로 유지됩니다.

컴파일러는 스토리가 유효하다고 알려줍니다. 클릭하며 살펴보는 것은 우연히 클릭한 경로가 작동한다는 것을 알려줍니다. Ink-Tester는 무작위 플레이스루를 반복적으로 샘플링하고 줄 수준 빈도를 보고합니다. 반면 inkcheck는 선택 상태를 체계적으로 탐색하고 짧은 실패 경로를 반환합니다. 핵심 차이는 반복 가능성입니다. 보고된 경로를 수정한 후 동일한 구성된 실행으로 해당 경로를 다시 확인할 수 있습니다. 이 두 접근 방식은 특히 무작위성이나 엔진 통합이 있는 스토리에서 상호 보완적입니다.

예시

$ inkcheck examples/manor.ink
✓ compiled — 92 words, 7 knots, 6 choices
✓ explored 18050 states within limits (depth 100, 10000000 states, seed 1) — exhaustive (every reachable state visited) — 5 distinct terminal state(s)
    terminal via [Enter in darkness → Search the study → Leave with your loot]: "You slip out the servant door, heavier by half a purse."
    ...
✗ 1 runtime error(s):
    obj is null or undefined (at cellar.3)
      repro: [Enter in darkness → Descend to the cellar] (found by dfs:last)
⚠ 1 knot(s) never visited on any explored path — unreached is not necessarily unreachable:
    treasure_vault (manor.ink line 35) — no authored divert points here — possible orphan

실행이 중단되면 보고서는 실제로 제한한 한도를 명명합니다. 예를 들어 ⚠ coverage is partial, not a proof — paths were cut at 30 choices deep; raise --max-depth to follow longer trails. 깊이와 상태 예산은 별개의 축입니다. The Intercept의 로컬 실행에서 --max-depth를 30에서 100으로 올리면 1,000,000 상태 예산으로 깊이 30에서 10배 더 큰 예산보다 더 많은 후반부 콘텐츠에 도달했습니다.

컴파일 또는 런타임 오류가 있으면 종료 코드가 0이 아닙니다. --strict를 추가하면 경고, 방문되지 않은 knot, 잘림, 외부 스텁에서도 실패하므로 부분 커버리지가 조용히 CI를 통과할 수 없습니다.

스토리가 기본 예산을 초과하기 위해 길 필요는 없습니다. Inkle이 게시한 The Intercept는 커뮤니티에서 비교적 작은 소스 파일로 간주되지만, Inkcheck는 여전히 5,000,000 상태에서 부분적이라고 보고합니다. 분기와 영구 변수는 보이는 선택 수가 시사하는 것보다 훨씬 큰 도달 가능 상태 그래프를 만듭니다. 소진은 소스 크기에서 추론된 기대가 아니라 관찰된 증명입니다. 유한 값을 가진 스토리는 원칙적으로 완전히 탐색 가능할 수 있지만 열거하기에는 비현실적일 수 있습니다. 턴, 무작위 또는 무제한 변수 상태는 의미적 그래프를 무한하게 만들 수 있습니다. 제한된 실행은 상태, 깊이, 시간, 메모리 중 먼저 도달하는 것에서 멈추고 어느 것인지 말합니다. 호스팅 검사기는 공유 작업을 1,000,000 상태로 제한합니다. 더 큰 작업(CLI의 100M 상한까지)은 로컬에서 수행해야 합니다. 크기 조정 지침은 성능 및 메모리를 참조하세요.

단일 실행에서 inkcheck는 하나의 순회 순서에 모든 것을 걸지 않고 보완적인 검색 패스들에 상태 예산을 분배한다. 현재 CLI 포트폴리오는 마지막 선택 우선, 첫 번째 선택 우선, 내부에서 외부로 확장하는 DFS 슬라이스를 탐색하고, 결정적 패스들이 반복하기 쉬운 초기 선택 접두사를 다양화하는 시드 기반 무작위 샘플링 슬라이스를 추가하며, 변수 시그니처 계보당 하나의 상태를 유지하면서 BFS처럼 레벨별로 진행하는 프런티어 상한 다양성 빔을 추가한 다음, 재현 경로를 줄이기 위해 작은 너비 우선 슬라이스를 예약한다. 무작위 슬라이스는 고정된 기본 시드를 사용하고 빔은 전혀 시드가 필요 없으므로 CI에서 실행이 재현 가능하게 유지된다. 보고된 모든 엔딩과 런타임 오류는 이를 찾은 패스(및 시드)를 명명한다. 이는 동일한 --max-states 제한에서 더 많은 엔딩과 도달 가능한 knot를 찾는 경우가 많지만, 여전히 제한된 QA이다. 잘린 보고서는 유용한 증거이지 완전한 증명이 아니다.

--search=shared는 실험적 대안을 선택한다. 심층, 참신 우선, 시드 기반 뷰는 하나의 중복 제거된 프런티어에서 가져오며 각 도달 가능한 상태는 최대 한 번만 확장된다. 이는 여러 전략이 그렇지 않으면 동일한 상태를 다시 발견하게 되는 상황에서 제한된 예산을 더 효율적으로 사용할 수 있다. JSON 텔레메트리는 대기 중 및 활성 체크포인트 JSON/변수, 유지된 증인 계보, 중복 제거 및 의미론적 인덱스, 프런티어 참조, 발견 결과를 구분한다. 또한 해제된 계보와 오래된 뷰 압축을 보고한다. 이는 결정적으로 회계 처리된 페이로드/구조 추정치이지 정확한 V8 힙 사용량이 아니다. 아직 기본값이 아니다. 일부 초기 선택 구조는 여전히 포트폴리오의 독립적인 무작위 및 빔 패스를 선호할 수 있다.

장기 실행 공유 작업을 평가하는 라이브러리 소비자는 exploreSharedResumable(...)를 사용할 수 있다. 예산이 남아 있으면 정확한 라이브 베이스 공유 프런티어를 포함하는 소스 바인딩된 버전 지정 JSON 체크포인트를 반환한다. 이후 호출은 총 허용량을 높이고(예: 100k에서 1m로) 처음 100k를 재생하지 않고 계속한다. 분할 실행 동등성은 중단 없는 실행과 대조하여 회귀 테스트된다. 이는 엔진 기반이지 아직 CLI 영속성 기능이 아니다. 체크포인트에는 작성된 텍스트, 변수, 런타임 상태 및 증인 경로가 포함될 수 있으며, 스키마 v1은 의도적으로 어서션, 목표, 변수/목표 인지 공유 모드를 제외한다. 공유 체크포인트 스키마 v1을 참조하라.

--search=shared-variable은 더 좁은 실험으로, 공유 프런티어 선택의 12.5%를 드문 변수 스냅샷 또는 전이를 통해 도달한 상태에 부여한다. 부스트는 제한되어 있으며 심층, 참신 우선, 시드 기반 뷰는 계속 활성화된다. 기계적으로 구동되는 스토리렛 그래프에 도움이 될 수 있지만 균일하게 더 나은 것은 아니다. 체크인된 비교 표에는 이득과 회귀가 모두 포함된다.

적응형 포트폴리오는 범용 기본값으로 유지된다. 실험 모드는 그 가중치나 동작을 변경하지 않는다. Inkcheck의 검색 전략 정책은 향후 기본값 변경 전에 필요한 벤치마크 범위와 회귀 게이트를 정의한다.

제한된 검색 vs 무작위 샘플링

Inkcheck는 사소하지 않은 이야기의 모든 가능한 상태를 방문하겠다는 약속이 아니다. 분기, 루프, 변수, 무작위 동작, 호스트 게임 통합은 완전한 커버리지를 물리적으로 비현실적으로 만들 수 있다. 무작위 샘플링에 비해 실질적인 장점은 재현성이다. 동일한 이야기와 제한이 주어지면 inkcheck는 선택 그래프를 체계적으로 탐색하고, 실패에 대한 정확한 선택 경로를 반환하며, 미방문 knot 단서를 보고하고, 실행이 부분적이었을 때 명시적으로 말한다.

무작위 샘플링은 특히 무작위성이 있거나 상태 공간이 거대한 이야기에 여전히 유용하다. 두 접근 방식을 상호 보완적인 것으로 취급하라. 무작위 플레이는 놀라운 경로를 우연히 발견할 수 있는 반면, inkcheck는 선언된 예산 안에서 결정적이고 CI 친화적인 증거를 제공한다.

로컬 테스트에서 깊이 제한 30으로 The Intercept를 실행했을 때, 더 높은 예산은 더 많은 종단 상태를 찾았지만 완전한 커버리지를 증명하지는 못했다. 타이밍은 하나의 로컬 개발 머신에서 측정된 것이며, 보편적 벤치마크가 아니라 규모 증거로 읽어야 한다.

Claude Code에 추가:

claude mcp add inkcheck -- npx -y inkcheck mcp

또는 모든 MCP 클라이언트 구성에 추가:

{
  "mcpServers": {
    "inkcheck": { "command": "npx", "args": ["-y", "inkcheck", "mcp"] }
  }
}

기본 MCP 프로필은 5개의 도구를 노출합니다: inkcheck_capabilities, inspect_story, compile_story, start_search, inkcheck_workflow. 이는 새 에이전트의 부트스트랩 컨텍스트를 작게 유지합니다. capabilities는 라우터의 논리 연산과 요청 필드를 나열합니다. 모든 연산을 별도의 명명된 도구로 요구하는 클라이언트에만 INKCHECK_MCP_PROFILE=full을 설정하세요.

간결한 에이전트 루프는 inkcheck_capabilities -> inspect_story -> compile_story -> start_search -> 파인딩/재생/회귀 연산을 inkcheck_workflow로 라우팅 -> 수정 -> 컴파일 및 검증입니다. 결과 창 세션은 지속적이고, 경계가 있고, 페이지네이션되며, 소스에 바인딩되므로 기본 에이전트 경로입니다. 논리적 start_campaign / continue_campaign 연산은 동일한 정확한 공유 프론티어 주변에 집계 정책과 측정된 지출/출처를 추가합니다. 일반 start_search / continue_search는 명시적 누적 허용량 제어를 유지합니다. 호출은 동기식이므로 취소는 반환된 지속 경계에서 신뢰할 수 있으며, 창 중간 선점이 아닙니다. inspect_search는 개인정보 최소화를 유지합니다. add_goal은 정확한 기본 검색을 약화시키지 않고 별도로 보고되는 지정 예산을 지출할 수 있으며, replay_witness는 하나의 현재 트랜스크립트, 선택 흔적, 변수 상태를 반환하는 명시적 경계입니다. 런타임 실패, 어서션 위반, 승인된 목표 증인에 대해 편집 전에 pin_regression, 편집 후에 check_regression을 실행하여 추가 검색 실행 없이 하나의 정확한 비공개 증인을 재생합니다. 핀은 광범위한 재검증이 아닙니다. 의미 있는 편집 후에는 새로 경계가 설정된 검색을 실행하세요. QA 증거 핀, 번들 스킬, MCP 결과 창 세션을 참조하세요.

작가나 에이전트가 스토리 규칙을 제안할 때, inkcheck_workflow가 먼저 review_contract를 실행할 수 있습니다. 검토는 컴파일된 스토리에 대해 타입이 지정된 어서션과 목표를 검증하고, 기존 계약을 목록화하며, 작성자 승인을 요구하고, 기본적으로 지정 예산 없이 광범위한 QA를 권장합니다. 이는 읽기 전용입니다: 구성을 편집할 수 없고, 검색 예산을 지출할 수 없으며, 목표 프로브를 조용히 승격할 수 없습니다. 에이전트 주도 QA 계약을 참조하세요.

CLI

inkcheck capabilities [--json]
inkcheck inspect <story.ink> [--json]
inkcheck <story.ink> [--max-depth N] [--max-states N] [--seed N] [--story-seed N] [--search=portfolio|shared|shared-variable] [--concurrency auto|N] [--max-frontier-states N] [--max-frontier-memory MB] [--auto] [--profile] [--next] [--no-min-repro] [--strict] [--save-report] [--save-checkpoint] [--progress=auto|human|ndjson|off] [--human|--json|--json-stream|--markdown]
inkcheck artifacts list [--json]
inkcheck artifacts show <report-id> [--json]
inkcheck artifacts findings <report-id> [--limit N] [--cursor C] [--json]
inkcheck artifacts finding <report-id> <finding-id> [--json]
inkcheck artifacts replay <report-id> <finding-id> [--json]
inkcheck artifacts delete <report-id> [--apply] [--json]
inkcheck artifacts prune --keep N [--apply] [--json]
inkcheck checkpoints list [--json]
inkcheck checkpoints show <checkpoint-id> [--json]
inkcheck resume <checkpoint-id> --max-states N [--json]
inkcheck mcp    # start the MCP server on stdio

inkcheck capabilities --json을 사용하면 에이전트가 스키마 버전, 제한, 검색 모드, 명시적 지원 또는 지원되지 않는 기능을 의존하기 전에 확인할 수 있습니다. inkcheck inspect story.ink --json은 컴파일이나 탐색 없이 결정적 소스 전용 발견을 수행합니다: 프로젝트 로컬 include를 따라가고 스토리 형태, 의미론, 외부 참조, knot/함수, 변수 선언/읽기/쓰기, 사실적 할당 사이트가 있는 정적 조건 게이트의 경계 있는 맵을 반환합니다. 지속적인 MCP 세션은 명시적으로 선택된 지원 게이트 하나를 별도의 경계 있는 probe_gate 목표 실행으로 전환할 수 있습니다. 이 루트 시작 프로브는 정확한 기본 프론티어를 보존하고 증인 또는 경계 있는 미스(miss)를 보고합니다. 게이트 검사와 할당 사이트는 전제 조건 힌트일 뿐이며, 도달 가능성 증명이나 기본 검색 할당의 변경이 아닙니다. 복합 게이트 검사 계약과 에이전트 발견 계약을 참조하세요.

게이트 프로브 평가 프로토콜은 초기 선택 조합 잠금과 옵트인 5M The Intercept 셀에서 동일 예산의 명시적 프로브와 일반 공유 검색을 비교합니다. 이는 추가 전제 조건 스티어링이 가치가 있는지에 대한 증거이며, 커버리지나 승격 주장이 아닙니다.

JSON 검사는 버전화된 보고서 스키마를 사용합니다. 파인딩에는 안정적인 ID와 정규화된 종류가 있습니다. 종료 및 런타임 오류 증인은 사람이 읽을 수 있는 선택 텍스트와 0 기반 선택 인덱스를 모두 포함하므로 중복 레이블도 playtest_story를 통해 정확히 재생 가능합니다. 봉투(envelope)는 Inkcheck 버전, 컴파일된 스토리 지문, 유효 구성, 바인딩 제한, 관찰 전용 shadowDecision을 기록하면서 기존 compile, stats, explore, nextRun 섹션을 유지합니다.

--concurrency auto는 로컬 포트폴리오 기본값입니다. 이는 네 개의 워커를 무조건 생성하는 것이 아니라 네 레인 상한을 설정합니다: 하나의 내부-외부 DFS 패스가 최대 1,024 상태까지 실행된 후, 스토리가 소진되거나, 깊이가 바인딩되거나, 작성된 knot가 이미 포화되었거나, 하드웨어에 코어가 하나뿐이거나, 메모리가 안전하게 워커를 지원할 수 없을 때 버전화된 분류기가 순차적으로 유지됩니다. 열린 지속 프론티어는 해당 라이브 패스를 부모에 유지하고, 접촉되지 않은 패스는 지속 워커에서 시작됩니다. --concurrency 1은 하드 순차 옵트아웃입니다. 명시적 값 2-16은 워크로드 분류 없이 고정 워커 상한을 유지합니다. 공유 검색과 추가 목표 실행은 명시적으로 호환되지 않는 고정 값을 요청하지 않는 한 자동으로 순차적으로 유지됩니다.

보고서는 concurrencyMode, 해결된 상한, 활성화 정책/결정/이유, 파일럿 작업, 유효 워커, 집계 힙 계획, 중복 평가(프로덕션 정책의 경우 0)를 노출합니다. 워커 실패는 최신 완료 증거를 유지하고 truncatedBy.worker를 보고합니다. 절대 상태 예산 중지로 위장하지 않습니다. 호스팅 배포는 자체 명시적 작업별 상한을 전달하며 프로덕션 컨테이너에서는 기본값 1이고, 실제 자식 취소는 임시 업로드를 정리합니다. V8/런타임 오버헤드는 힙이 아니므로 최고 RSS는 더 높을 수 있습니다. 분류기는 워크로드 형태를 추정할 뿐 커버리지 완전성을 추정하지 않습니다.

MCP는 기본적으로 간결한 머신 출력을 사용합니다: 검사는 16KiB로 제한되고, 컴파일, 통계, 일회성 탐색, 결과 창 응답은 32KiB로 제한됩니다. 출력 누락은 경계 있는 검색 잘림과 별도로 보고됩니다. 전체 스토리 포함 보고서는 명시적 상세 또는 드릴다운 호출을 통해서만 사용할 수 있습니다.

저장된 보고서는 전체 보고서를 로드하지 않고 경계 있는 파인딩 드릴다운을 지원합니다. artifacts findings는 기본적으로 최대 20개의 개인정보 최소화 요약을 반환하며(최대 100), 보고서 바인딩 커서를 포함합니다. 요약은 스토리 산문, 변수, 선택 텍스트, 증인 경로를 생략합니다. artifacts finding은 하나의 완전한 안정적 파인딩을 가져옵니다. artifacts replay는 저장된 진입점을 재컴파일하고 저장된 스토리 시드로 해당 파인딩의 인덱스된 선택을 따르지만, 아티팩트 신선도가 current인 경우에만 가능합니다. 오래되었거나 이동된 소스는 실패 폐쇄(fail closed)됩니다.

보고서 저장은 비공개이며 경계가 있습니다: 하나의 보고서는 최대 256MiB를 사용할 수 있고, 한 프로젝트의 모든 보고서는 최대 1GiB를 사용할 수 있습니다. 두 상한 중 하나를 초과하는 저장은 기존 증거를 삭제하지 않고 실패합니다. artifacts delete와 artifacts prune --keep N은 기본적으로 미리보기이며 --apply로만 변경합니다. prune은 각 진입점에 대해 최신 N개의 보고서를 유지하고 호출당 최대 100개를 제거합니다. 이 명시적 수명 주기는 다른 실행이 완료되었다는 이유만으로 안정적인 보고서 ID가 사라지지 않도록 보장합니다.

유지보수자는 매니페스트 기반 섀도우 정책 평가기로 독립적인 예산 실행 전반의 섀도우 권장 사항을 비교할 수 있습니다. 별도의 검색 승격 벤치마크는 체크인된 20개 패밀리 코퍼스와 고정된 동의 기반 작성 프로젝트 계층에서 일치하는 기준/후보 행렬을 실행하고, 리소스 관찰과 최악 패밀리/프로젝트 손실을 보고하며, 절대 승자를 선언하지 않습니다. 첫 번째 작성 프로젝트 평가는 셀이 완료된 곳에서 동등성과 의미 있는 프로젝트 형태 리소스 제한을 발견했지만 정책 v2 이점은 없었습니다. 두 도구 모두 경계 있는 대규모 실행을 오라클이라 부르거나 기본 정책을 변경하지 않습니다.

--max-depth는 1-1,000을 허용하고 --max-states는 1-100,000,000을 허용하며, 기본 예산은 10,000,000입니다. 이러한 하드 상한은 잘못된 자동화 입력이 실수로 탐색 경계를 비활성화하는 것을 방지합니다. 기본값은 의도적으로 공격적입니다. 큰 예산이 무모하지 않고 안전하게 만드는 세 가지 이유가 있기 때문입니다: 완전히 탐색 가능한 스토리는 체계적 패스가 완전함을 증명하는 순간 조기 종료되고(따라서 작은 스토리는 여전히 소수의 상태에서 완료됨), 메모리 가드는 메모리 부족 크래시 전에 깨끗하게 멈추며, 진행 보고를 통해 긴 실행을 지켜보고 중단할 수 있습니다. 따라서 크고 비완전한 스토리는 해당 예산을 사용할 것입니다 — CI에서 실행하기 전에 성능 및 메모리를 참조하고, 경계 있는 런타임이 커버리지 깊이보다 중요하다면 더 작은 --max-states를 고정하세요.

--max-states는 실행의 총 예산이며, 단일 DFS 워크가 모든 상태를 소비한다는 약속이 아닙니다. 기본적으로 CLI는 해당 예산의 대부분을 선택 트리의 세 가지 보완적 DFS 뷰와 시드된 무작위 샘플링 슬라이스에 분할하고, 더 짧은 실패 및 종료 재생 경로를 위해 작은 너비 우선 슬라이스를 유지합니다. --no-min-repro를 사용하여 너비 우선 단축이 광범위한 검색보다 덜 중요할 때 해당 재생 슬라이스를 DFS 포트폴리오에 사용하세요.

--seed(기본값 1)는 Inkcheck의 무작위 샘플링 검색 슬라이스만 제어합니다. --story-seed(기본값 1)는 RANDOM() 및 셔플 동작에 대한 Ink의 초기 런타임 RNG 상태를 독립적으로 설정합니다. 반복 가능한 CI와 정확한 증인 재생을 위해 둘 다 고정하세요. 다른 선택 워크를 샘플링하려면 --seed를 변경하고, 다른 유효한 스토리 무작위성 시퀀스를 실행하려면 의도적으로 --story-seed를 변경하세요. 작성된 SEED_RANDOM(...) 명령은 여전히 적용되며 초기 스토리 시드를 재정의할 수 있습니다. Inkcheck는 두 시드를 기록하고 재생 지침에 storySeed를 포함하지만, 한 번의 실행이 가능한 모든 스토리 시드를 열거하지는 않습니다. --json 출력의 각 파인딩 foundBy 필드는 이를 발견한 패스를 명명합니다(예: dfs:last 또는 random:seed=1).

--search=shared는 실험적 공유 상태 다중 프론티어 엔진을 선택합니다. --search=portfolio는 변경되지 않은 기본값입니다. 공유 모드는 고정 시드에 대해 결정적이며 깊이, 상태, 메모리, 시간, 진행, 재생 단축 제어를 여전히 존중합니다.

--save-checkpoint는 일반 공유 검색보다 의도적으로 좁습니다: 같은 명령에서 --search=shared --no-min-repro와 어서션 없음, 목표 없음, --auto 없음, --next 없음, 보고서 아티팩트 없음을 요구합니다. 라이브 작업이 남아 있으면 JSON 출력에 소스 바인딩 체크포인트 ID가 포함됩니다. inkcheck resume <id> --max-states N은 소스와 검색 바인딩이 일치하고 N이 체크포인트의 이전 총 허용량을 초과해야 합니다. 자동으로 다음 세대를 저장합니다. 완료된 및 리소스 중지된 검색은 재개 가능한 체크포인트를 발명하지 않고 보고서를 반환합니다.

--search=shared-variable는 공유 검색에 작은 변수 희소성 프론티어를 추가합니다. 관찰된 드문 변수 값을 우선시하고 기계적으로 변경합니다. AI를 사용하지 않으며, 스토리 의미를 이해하지 않으며, 어떤 값이 바람직한지 추론하지 않습니다.

--max-frontier-states 및 --max-frontier-memory는 유지되는 보류 중인 검사점을 위한 선택적 공유 검색 안전 상한입니다. 둘 다 기본값이 없습니다. Inkcheck는 보편적인 낮은 프런티어 상한을 부과하지 않습니다. 명시적 상한이 적용되면 실행은 발견한 내용을 유지하고 truncatedBy.frontier를 보고하며 중단을 상태 예산 소진으로 잘못 표시하지 않습니다. 동일한 제어는 ci.maxFrontierStates / ci.maxFrontierMb 및 MCP explore_story 입력으로도 제공됩니다.

--max-memory <mb>은 전체 실행이 깨끗하게 중단되기 전에 사용할 수 있는 힙의 양을 제한합니다. V8 힙 메모리 부족 중단은 사후에 포착할 수 없으므로 inkcheck는 탐색 중 메모리를 감시하다가 충돌하기 전에 중단하고, 지금까지 찾은 모든 것을 유지하며, 실행을 잃는 대신 부분 보고서와 함께 truncatedBy.memory를 보고합니다. 명시적 상한은 최종 결과 구성과 플러시를 위해 최대 25%(최대 1GiB)를 유지합니다. 제한된 스트림은 전체 상한과 더 낮은 검색 워터마크를 모두 보고합니다. 기본 상한은 V8 힙 제한의 85%입니다(설정한 NODE_OPTIONS=--max-old-space-size를 존중합니다). 따라서 사양이 낮은 하드웨어에서 대규모 실행은 죽는 대신 우아하게 성능이 저하됩니다. 상한을 조이거나 느슨하게 하려면 명시적 값을 전달하세요. 메모리 중단 시 nextRun 판정은 investigate입니다(--max-old-space-size를 올리거나 --max-states를 낮추거나 스토리를 분할). 예산을 더 투입하면 더 빨리 한계에 부딪힐 뿐이므로 절대 broaden이 아닙니다.

--max-time <s>은 총 벽시계 시간 상한입니다. 마감 시한은 컴파일과 소스 스캔 전에 시작되며, 실행은 유지된 발견 결과를 병합하고 결과를 플러시하기 위해 할당량의 10%(최소 250ms, 최대 60초)를 보유합니다. 탐색은 상태 예산까지 실행하는 대신 truncatedBy.time으로 중단됩니다. 로컬 CLI에는 기본 시간 제한이 없습니다. 이는 CI 또는 제한된 실행 시간이 필요하면서도 지금까지의 발견 결과는 여전히 원하는 모든 상황을 위한 것입니다. 메모리 가드와 동일한 우아한 부분 결과 방식을 시간에 적용한 것입니다. 호스팅된 웹 검사기는 하드 타임아웃 바로 아래에서 이 값을 자동으로 설정하므로 느린 스토리는 종료되는 대신 부분 보고서를 반환합니다.

--profile은 탐색을 실행하지 않고 스토리의 저렴한 정적 형태 프로필(변수와 변수가 할당된 위치, 선택 밀도, 가장 긴 divert 경로)과 inkcheck가 해당 형태에 대해 선택할 깊이 제한 및 패스 가중치를 출력합니다. --auto는 이러한 제안을 적용합니다. 정적 divert 경로가 기본값을 초과하면 --max-depth를 올리며(절대 낮추지 않고, 명시적 플래그가 항상 우선합니다) 프로필의 패스 가중치를 포트폴리오에 전달합니다. 메인 경로가 40개 선택만큼 깊은 스토리의 경우 기본 설정은 아무것도 찾지 못하지만, --auto는 결말에 도달하고 약 111개 상태에서 스토리가 완전함을 증명합니다.

대화형 터미널은 기본적으로 간결한 실시간 진행 줄을 표시합니다. 실제 단계, 구성된 작업 예산 대비 탐색된 상태, 발견 사항, 경과 시간입니다. --progress=human은 CI 로그용으로 읽기 쉬운 스냅샷을 강제합니다. --progress=ndjson은 에이전트와 파서를 위한 버전 관리 이벤트를 작성하고, --progress=off는 진행 표시를 끕니다. 이 백분율 중 어느 것도 스토리 적용 범위를 주장하지 않습니다. 최종 stdout 보고서는 여전히 권위가 있으며, 진행 표시에는 스토리 산문, 선택지, 변수 또는 소스 조각이 포함되지 않습니다.

모든 보고서에는 nextRun 판정도 포함됩니다. 이 판정은 보고서 자체에서 결정론적으로 계산되는 소규모 고정 어휘(stop, deepen, broaden, reseed, investigate)로, 구체적인 플래그, 사용한 필드를 인용하는 근거, 증거 기반 기대 이득을 함께 제공합니다. --next는 이에 따라 동작합니다. 검사 후 inkcheck는 권장된 확대를 적용하고 최대 세 번까지 다시 실행하며, stop/investigate 판정, 플래그 상한에 도달하거나 확대된 실행이 새로운 것을 찾지 못하면(고정점) 중단합니다. 실행별 추적은 --json 출력에 runs로 기록되며, 단계 설명은 stderr로 전달되어 기계 출력이 깨끗하게 유지됩니다. 권장 사항은 문서화된 하드 상한을 절대 초과하지 않습니다. 플래그 증가를 뒷받침할 증거가 없으면 판정은 investigate로 낮아지고 검토할 가치가 있는 매듭을 가리킵니다.

GitHub Actions:

- uses: actions/setup-node@v4
  with: { node-version: 22 }
- name: Check the story and publish a readable summary
  shell: bash
  run: |
    set -o pipefail
    npx -y inkcheck story/main.ink --strict --markdown --max-states 500000 | tee -a "$GITHUB_STEP_SUMMARY"

예제는 --max-states 500000을 고정하여 작업의 실행 시간을 예측 가능하게 만듭니다. 기본 예산은 10,000,000이며, 크고 완전하지 않은 스토리는 실제로 그 예산을 소진합니다(성능 및 메모리 참조). 최대 적용 범위보다 제한된 실행 시간이 더 중요할 때는 CI에서 예산을 고정하세요.

--strict는 경고와 방문하지 않은 매듭뿐만 아니라 탐색이 잘렸거나 EXTERNAL 함수를 스텁 처리해야 했을 때도 실패합니다. 이렇게 하면 부분 검사가 녹색 '완료' 배지를 받는 것을 방지합니다.

작가 친화적인 설정과 보고서 해석에 대한 도움은 InkJam QA 가이드를 참조하세요.

오해의 소지가 있는 결과를 찾으셨나요? 공개 이슈 양식을 사용하여 잘못되었거나 누락된 결과를 신고하거나, 라이선스가 부여된 최소 픽스처를 제공하거나, 옵트인 QA 클리닉 검사를 요청하세요. 비공개, 엠바고 또는 잼 제한 스토리 자료를 공개 이슈에 첨부하지 마십시오.

사람, CI, 에이전트를 위한

inkcheck는 터미널의 사람, CI 작업, 또는 선택적 AI 코딩 에이전트가 구동할 수 있습니다. 도구 자체는 여전히 AI를 사용하지 않습니다. 에이전트는 CLI 또는 MCP 서버의 또 다른 호출자일 뿐입니다.

• 기계 판독 가능 인터페이스: 리포지토리 루트의 tool.json은 CLI 플래그, MCP 도구, 종료 코드, --json / --json-stream 출력 형태를 하나의 파일로 설명합니다.

• --json 전체 보고서를 stdout에 단일 JSON 객체({ compile, stats, explore })로 내보냅니다. 보기 좋게 출력된 결과를 스크래핑하는 대신 그 JSON을 파싱하세요. explore.passes는 크기가 제한된 패스 로컬 discoveryCurve('이 탐색기가 찾은 것')와 포트폴리오 전용 portfolioMarginalCurve('이 탐색기가 처음으로 추가한 것')를 유지하며, 정확한 터미널, 가시적 결과, 런타임 오류, 어서션, 목표/단계, 매듭, 비교 가능한 참신성을 구분합니다. 요약은 압축에도 불구하고 첫 번째/최신 발견 상태와 무발견 간격 사실을 보존합니다. 포트폴리오 보고서에는 실제 인터리브 실행 순서의 실행 전체 곡선도 포함됩니다. 벽시계 시간은 진행 이벤트에서 관찰용으로만 유지됩니다. explore.schedule은 적응형 라운드가 예산을 어떻게 사용했는지 보여줍니다. 버전이 지정된 shadowDecision은 미래의 anytime 정책이 무엇을 권장하고 그 이유를 보여주며, 보호된 패스별 하한과 불확실성을 포함합니다. 이 값은 관찰 전용(applied: false)입니다. 현재 검색을 변경하거나 제한된 적용 범위가 증거라고 주장하지 않습니다.

• --json-stream 유지되는 재생 가능한 숫자 발견 증인을 NDJSON으로 내보낸 다음, 전체 강화 보고서나 보고서 크기의 JSON 문자열을 구체화하는 대신 제한된 터미널 요약을 내보냅니다. 현재 --concurrency 1이 필요하며, 하나의 탐색 실행만 지원하고(--next 또는 --profile 없음), --save-report와 결합할 수 없습니다. 예약된 숫자 태그 모드는 oracle 변수를 검색에 노출하지 않고 모든 일반적인 엔딩을 스트리밍하지 않으면서 InkBench의 oracle 중립 점수를 지원합니다. 하드 래퍼 경계에서 부분 증거가 살아남아야 하는 긴 외부 프로세스 평가에는 스트림을 사용하세요. 제한된 증거 스트림 계약을 참조하세요.

• --progress=ndjson 에이전트 또는 CI 로그 파서를 위해 버전이 지정된 수명 주기 및 작업 진행 이벤트를 stderr로 내보냅니다. statesExplored / stateBudget은 예산 사용량이지 스토리 적용 범위가 아닙니다. 최종 stdout 보고서가 여전히 권위 있는 소스입니다. NDJSON 진행 계약을 참조하세요.

• --human 오류, 경고, 참고 사항으로 그룹화된 우선순위 수정 목록을 내보내며, 가능한 경우 파일/줄 위치, 런타임 실패에 대한 선택 경로, 각 발견 항목에 대한 다음 단계를 포함합니다.

• --markdown CI를 검토하는 사람들을 위한 GitHub Step Summary 친화적 보고서를 내보냅니다.

• 결정적 종료 코드: 0 정상 · 1 컴파일/런타임 오류(또는 --strict에서는 경고, 방문하지 않은 매듭, 잘림, 외부 스텁) · 2 사용법 오류. 종료 코드로 분기하세요. 텍스트를 grep하지 마세요.

• MCP: claude mcp add inkcheck -- npx -y inkcheck mcp는 간결한 5-도구 에이전트 프로필을 노출합니다. 호환성 카탈로그에는 INKCHECK_MCP_PROFILE=full을 사용하세요.

• 루프: .ink 편집 -> compile_story -> start_search -> inkcheck_workflow를 통해 다음 증거 작업 라우팅 -> 수정 -> 컴파일 및 검증. inkcheck는 생성했거나 편집한 스토리 그래프에 대한 반복 가능한 기계적 검사입니다. 반환하기 전에 자신의 작업을 검증하는 데 사용하세요.

• 커버리지 루프: explore_story(및 CLI --json)는 nextRun을 반환합니다. 해당 recommendation(stop / deepen / broaden / reseed / investigate)에 따라 분기하고 stop: true가 될 때까지 nextRun.flags로 다시 실행하세요. 또는 CLI가 직접 처리하게 할 수 있습니다: inkcheck story.ink --next.

리포지토리 루트의 llms.txt는 위의 모든 내용을 간결하고 모델 친화적으로 요약한 것입니다.

작동 방식

• 컴파일은 표준 컴파일러인 inklecate를 사용합니다. $INKLECATE_PATH, 그다음 PATH 순서로 찾은 뒤, 최초 실행 시 고정된 공식 ink 1.2.1 릴리스에서 ~/.cache/inkcheck로 자동 다운로드됩니다. 다운로드된 아카이브는 압축 해제 전에 고정된 SHA-256 해시로 검증됩니다. 스토리는 -c로 컴파일되어 모든 매듭 방문이 집계됩니다.

• 탐색은 컴파일된 스토리를 inkjs(공식 JS 런타임 포트)에서 실행합니다. 풀링된 스토리 인스턴스를 재사용하므로 컴파일된 JSON은 패스당 한 번만 파싱되고 상태는 LoadJson으로 되감습니다. Inkcheck는 --story-seed(기본값 1)에서 스토리 난수를 초기화한 다음 저장된 모든 분기에서 Ink의 RNG 상태를 보존합니다. 작성된 SEED_RANDOM(...)은 실행될 때 여전히 최종 권위를 가집니다. 상태는 콘텐츠 해시로 중복 제거됩니다. INCLUDE도 적용됩니다.

• CLI는 제한된 적응형 포트폴리오 검색을 사용합니다. 보완적인 패스들 — 마지막 선택 우선, 첫 선택 우선, 내부-외부 DFS, 다양성 우선 빔, 시드 기반 무작위 워크 — 은 10개의 결정적 라운드에서 인터리브 방식으로 실행됩니다. 초기 가중치(대략 20/20/26/15/20%, 또는 --auto에서 형태 프로필의 제안)는 발견이 여전히 증가하고 있는 패스 쪽으로 매 라운드 재배분되며, 활성 패스당 의도된 8%의 비율 하한이 적용됩니다. 연구 전용 정책 리플레이는 그 의도를 감사 가능한 누적 정수 서비스로 전환하고, 최신성을 전역 상태 수 대신 각 패스의 관찰된 실행 윈도우를 기준으로 정규화합니다. 수익률을 추정하기 전에 세 개의 윈도우를 요구하며, 갱신 없이 측정된 윈도우가 한두 개 지나면 신호를 만료시키고, 갱신된 런타임/어서션 증거 또는 명시적 목표 진행이 있을 때만 실험적 할당 오버레이를 허용합니다. 광범위한 커버리지는 기존 스케줄러에 남습니다. 프로덕션 스케줄러는 전체 승격 코퍼스를 통과할 때까지 변경되지 않습니다. 패스들은 서로 보완적입니다. DFS 순서는 하위 트리를 체계적으로 소진하고, 빔은 하드 프론티어 상한 안에서 변수 상태 계보에 걸쳐 예산을 분산하며, 무작위 워크는 모든 선택 지점을 다시 굴려 초기 선택 조합이 반복 대신 샘플링됩니다. 발견 사항은 하나의 보고서로 병합되며 각각 발견한 패스가 라벨로 붙고, 실행된 일정은 --json 출력에 나타납니다.

• 워크로드 인식 --concurrency auto는 로컬 포트폴리오의 기본값입니다. 그 실시간 1,024상태 내부-외부 DFS 파일럿은 일반적인 첫 번째 적응 라운드의 접두부가 된 다음, 순차적으로 계속되거나 제한된 영구 워커에서 아직 처리되지 않은 패스와 겹쳐 실행됩니다. 그 파일럿 중 시간이나 메모리가 제약으로 작용하거나, 워커가 초기화되기 전에 마감 시각이 도래하면 유효한 파일럿은 명시적으로 리소스 제약으로 잘린 부분 보고서로 반환되며, 상태 예산 소진으로 잘못 표시되지 않습니다. 80-셀 100K 게이트는 정확한 발견, 증명, 적응형 일정을 두 번의 열린 프론티어 활성화만으로 유지했습니다. 대응되는 5M The Intercept depth-30/depth-100 게이트는 정확한 증거를 유지하고, 깊이 제한 작업을 거부했으며, 지속 작업을 657.7초에서 489.0초로 개선했습니다. 모든 상태는 하나의 상한 안에 머물고 중복 파일럿 평가는 0입니다. 명시적 1은 순차 실행을 유지하고, 명시적 2-16 상한은 고정 동시성을 유지합니다. 동시성 평가를 참조하세요.

• 실험적 --search=shared는 하나의 전역 상태 정체성을 유지하고 대기 중인 작업을 깊이, 참신성, 시드 기반 프론티어 뷰를 통해 노출합니다. 어떤 뷰에서 선택된 상태는 한 번만 확장됩니다. 확장된 체크포인트 JSON은 즉시 해제되고, 컴팩트한 부모 링크는 대기 중인 하위 항목이 정확한 재현 경로를 필요로 하는 동안에만 유지되며, 오래된 뷰 ID는 주기적으로 컴팩트됩니다. 보고서는 컴포넌트별 회계와 선택적 명시적 체크포인트 봉투를 노출합니다. 변수 상태 및 변수 전이 희소성은 평가 텔레메트리로 기록됩니다.

• 실험적 --search=shared-variable은 공유 프론티어 선택 여덟 개마다 하나를 변수 희소성 뷰로 대체합니다. 그 점수는 대상 변수 스냅샷의 관찰 빈도와 해당 엣지에서 가장 희귀한 변경을 결합합니다. 고정된 할당량 이상을 소비할 수 없으므로 그래프 참신성, 깊이, 시드 기반 탐색이 계속 대표됩니다.

• 체계적 패스가 어느 하나라도 한계에 부딪히지 않고 모든 도달 가능한 상태를 방문하는 순간 전체 포트폴리오는 중지됩니다. 그 이후의 모든 상태는 중복이기 때문입니다. 기본 10,000,000상태 예산에서 완전히 탐색 가능한 작은 스토리는 실제로 가진 몇 안 되는 상태에서 여전히 완료됩니다. 스토리가 완전 탐색 가능하면 큰 기본값은 비용이 들지 않습니다.

• 빔 패스는 "빔이 무엇을 최적화해야 하는가"에 구체적으로 답합니다. 생존자는 변수 시그니처 그룹 전체에서 라운드 로빈으로 선택되고(다양성 우선), 각 그룹 내에서는 참신성 순으로 순위가 매겨집니다 — 새로 방문한 매듭, 그다음 새 변수 시그니처, 그다음 새 제시된 선택지 집합. 시드 없이도 결정적이며, 도달 가능한 상태를 가지치기해야 할 때마다 실행을 잘림으로 보고하므로 빔은 결코 조용히 완전한 커버리지를 주장하지 않습니다.

• --no-min-repro로 건너뛰지 않는 한, CLI는 요청된 --max-states 예산의 약 10%를 너비 우선 재현 축소 슬라이스용으로 예약합니다. BFS는 가능하면 더 짧은 선택 경로로 공유 발견에 도달하며 추가적인 얕은 발견을 기여할 수 있습니다.

• 경계(--max-depth, --max-states)는 최악의 조합 폭발을 억제하며, 보고서는 잘렸을 때 명시적으로 알립니다.

커버리지 한계

• 탐색은 제한적입니다. 잘린 보고서는 방문한 상태에 대한 증거이지 전체 스토리에 대한 증명이 아닙니다.

• 보고서는 실행된 제한(깊이, 상태 예산, 검색 시드, 스토리 시드)을 명시하고, 잘린 경우 실제로 커버리지를 끊은 제한(--json의 truncatedBy, memory 포함)과 어떤 플래그를 올릴지에 대한 맞춤 조언을 제공합니다.

• 메모리를 소진하게 될 대규모 실행은 충돌하지 않고 깨끗하게 중지되어 부분 보고서(truncatedBy.memory)를 반환합니다. 메모리 사용량은 중복 제거 해시 집합(고유 상태 수에 거의 선형)과, 반복이 적은 깊은 스토리의 경우 너비 우선 재현 프론티어가 지배하므로, 스토리가 너무 커서 완료할 수 없을 때는 --no-min-repro와 더 타이트한 --max-states가 조정 수단입니다.

• 작은 스토리는 종종 반대되는 보장을 받습니다. 체계적 패스가 한계에 부딪히지 않고 모든 도달 가능한 상태를 방문하면 보고서는 이를 알려주며(exhaustive), 샘플링 슬라이스 예산 소진은 더 이상 잘림으로 간주되지 않습니다.

• EXTERNAL 함수는 호스트 게임을 사용할 수 없으므로 0으로 스텁됩니다. 보고서는 모든 스텁의 이름을 명시하며, 엄격 모드는 완전한 커버리지를 주장하는 대신 실패합니다.

• 무작위 동작은 보고된 스토리 시드에 대해 반복 가능하지만, 한 번의 실행이 모든 가능한 스토리 시드를 열거하지는 않습니다. 결과 빈도가 중요할 때는 의도적으로 --story-seed를 다양화하고 인간 플레이테스트를 계속 포함하세요.

• 방문되지 않은 매듭은 의도적으로 휴면 상태이거나, 엔진이 진입했거나, 도달 불가능할 수 있습니다. 인바운드 다이버트 분류는 아마도 고아일 콘텐츠와 아마도 한계에 묶인 콘텐츠를 구분하지만, 이는 검토 프롬프트이지 자동 삭제 지시가 아닙니다.

로드맵

• 로드맵은 제품 및 엔지니어링 진실 스코어카드의 적용을 받습니다. 모든 에픽은 제한 커버리지 정직성, 중요 증거 보존, 결정적 재생, 리소스 상한을 약화시키지 않으면서 측정된 가치를 개선해야 합니다.

• 커버리지 투명성: 잘림, 깊이 제한, 방문한 엔딩, 건너뛴 검색 공간, 탐색되었거나 탐색되지 않은 것에 대한 더 명확한 보고.

• 보고서 품질: 더 나은 소스 위치, 더 짧은 재현 경로, 안정적인 이슈 식별자, 런타임 오류, 방문되지 않은 매듭, 커버리지 제한의 더 명확한 그룹화.

• 작성자 정의 스토리 어서션: "골드가 절대 음수가 되지 않는다", "체력이 최대를 초과하지 않는다", "필수 변수가 엔딩 전에 설정된다" 같은 결정적 프로젝트 규칙.

• 목표 지향 변수 검색: 작성자와 에이전트가 승인된 상태를 찾을 수 있게 하되, 보호된 일반 검색 예산과 정확한 제한 커버리지 표현을 유지.

• 선택적 호스팅 AI 목표 어시스턴트: 비기술적 작성자가 승인을 위해 변수 목표와 어서션을 제안하도록 돕고, 이후 모든 실행과 검증을 Inkcheck의 결정적 비-AI 엔진에 위임하는 일급(first-class)이며 명시적으로 활성화되는 인간 인터페이스. 공급자, 동의, 소스 공유, 보존, 비용, 비활성화 컨트롤이 명시적이어야 하며, 생성된 규칙은 절대 조용히 신뢰되거나 적용되지 않습니다.

• 재현 지속성: 알려진 실패 경로를 기억하고, 탐색 전략이 개선되어도 향후 실행이 계속 확인하도록 보장.

• 컴팩트 캠페인 체크포인트: 체크포인트 아티팩트가 메모리나 디스크를 지배하지 않도록 유용한 대형 스토리 프론티어를 유지 및 재개하고, 직렬화 한계 전에 불변 부분 보고서로 폴백.

• 공개 호환성 픽스처: 회귀 테스트, 성능 비교, 신뢰 구축을 위한 동의 안전 예제와 합성 엣지 케이스.

• 에이전트 준비 상태: 실행 가능한 에이전트 준비 벤치마크는 숨은 힌트 없음 프로토콜, 결정적 런타임/어서션 픽스처, 부트스트랩/도구/참조/안전/증명 대상, 머신 스코어러, 별도의 도구/스킬/모델/환경 기여도를 고정합니다. 서로 다른 에이전트 구현에서 나온 두 번의 통과 관찰 실행이 릴리스 게이트(#67)로 남아 있습니다.

• 검색 승격 하네스: 실험적 전략이 기본값을 변경할 수 있기 전에 구조적 패밀리, 예산, 깊이, 시드 전반에 걸친 광범위하고 사전 선언된 스코어카드.

• 제한된 전문가 검색: 기계적 형태를 감지하고 복합 게이트, 루프/카운터, 스토리렛 적격성, 어서션 경계, 행동 프론티어 다양성(#107-#112)을 위한 소형 전문 프로브를 파견합니다. 전문가는 포트폴리오에 새로운 가치를 통해 확장을 획득하고 보호된 일반/롱테일 작업을 유지합니다.

• 대형 스토리 성능 컨트롤: 더 명확한 시간/커버리지 트레이드오프를 제공하는 빠른, 표준, 심층 검사 프리셋.

• 구조적 린트 검사: 누락된 태그, 일관되지 않은 태그 스키마, 프로젝트별 메타데이터 규칙에 대한 선택적 검사.

라이선스

MIT