lee-spec-kit 0.6.25 → 0.6.27

package/README.en.md

@@ -294,6 +294,7 @@ Use `context --json` only when full-detail debugging fields are required.
 - `approvalRequest`: ready-to-use approval/execute guidance (`labels`, `approveCommand`, `executeCommand`, `options[]`)
 - `requiredDocs`: built-in docs to read before the current action (`id`, `command`)
 - `checkPolicy`: approval validation policy (`token`, `acceptedTokens`, `tokenPattern`, `validLabels`, `contextVersion`, ...)
+- `agentOrchestration`: main-agent (conversation/approval) + sub-agent (execution) contract (`mode`, `delegationPolicy`, `delegateCommandExecution`, `longRunningCategories`, `fallbackToMainAgentWhenSubAgentUnavailable`, `pauseAndReportWhen`, `resumePriority`)
 
 **Advanced/reference fields (automation edge cases or debugging)**
 
@@ -363,8 +364,13 @@ npx lee-spec-kit flow F004 --request "promote issue 004 to F004 and proceed" --a
 # with default preset configured, request-only auto mode is available
 npx lee-spec-kit flow F004 --request "promote issue 004 to F004 and proceed"
 
+# long-running auto: create checkpoint + resume
+npx lee-spec-kit flow F004 --auto-until-category pr_create,code_review,pr_status_update --start-auto --json-compact
+npx lee-spec-kit flow --resume <RUN_ID> --json-compact
+
 # JSON output for automation
 npx lee-spec-kit flow --json
+npx lee-spec-kit flow --json-compact
 
 # strict checks (optional)
 npx lee-spec-kit flow --strict
@@ -375,12 +381,15 @@ npx lee-spec-kit flow --strict
 | Option            | Description |
 | ----------------- | ----------- |
 | `--json`          | JSON output for agents |
+| `--json-compact`  | Compact JSON output for agents (implies `--json`, reduced duplication) |
 | `--component <id>`| Select target component in multi mode (e.g. `app`, `api`, `worker`) |
 | `--all`           | Include completed features when auto-detecting |
 | `--done`          | Show completed (workflow-done) features only |
 | `--request <text>` | In auto mode, apply a new user request first (auto-selects `user_request_replan`) |
 | `--auto-preset <name>` | Use a named auto preset (builtin: `pr-handoff`) |
 | `--auto-until-category <categories>` | Auto-execute command actions until one of target categories appears (comma-separated) |
+| `--start-auto`     | Persist auto checkpoint (run id) and include resume metadata (`autoRun.run`) in JSON |
+| `--resume <run-id>`| Resume stored auto checkpoint by run id |
 | `--approve <reply>` | Pass through context label approval (e.g. `A`, `A OK`, `A proceed`) |
 | `--execute`       | Execute approved option when it is a command (ticket is required only when `requiresUserCheck=true`) |
 | `--execute-strict`| With `--execute`, fail if approved option is instruction-only |
@@ -391,9 +400,20 @@ Auto gate mode rules:
 - Auto mode (`--auto-until-category` / `--auto-preset`) cannot be combined with `--approve` or `--execute`.
 - `--request` requires auto mode.
   - Exception: if `workflow.auto.defaultPreset` is configured, `--request` alone enables auto mode.
+- `--resume <run-id>` cannot be combined with `<feature-name>`, `--component`, `--all`, `--done`, `--auto-*`, or `--request`. (It uses settings from the stored checkpoint.)
 - Auto-run stops as `gate_reached` when a target category appears, then prints that step's approval text (`approvalRequest.userFacingLines`).
+- If the current action set is instruction-only (no executable command), auto-run may stop with `AUTO_MANUAL_REQUIRED`. This is an automation boundary, not a CLI crash.
 - If progress stalls (same context/action repeating), it stops with `AUTO_NO_PROGRESS`.
-- In JSON mode, inspect `autoRun.status`, `autoRun.reasonCode`, `autoRun.gate`, and `autoRun.executions`.
+- In JSON mode, inspect `autoRun.status`, `autoRun.reasonCode`, `autoRun.gate`, `autoRun.executions`, and `autoRun.resume`.
+- Inspect JSON `agentOrchestration` for main/sub-agent responsibilities and pause/report boundaries.
+  - When `delegateCommandExecution: "long_running_only"`, keep short steps in the main agent and delegate only categories listed in `longRunningCategories`.
+- With `--start-auto`, JSON also includes `autoRun.run` (`runId`, `status`, `resumeCommand`).
+
+Agent resume rules (recommended):
+- When `flow --json-compact` (or `flow --json`) returns `autoRun.enabled=true`, resume with `autoRun.resume.flowCommand` after interruption/compression.
+- If you need a fresh checkpoint before resuming, run `autoRun.resume.contextCommand` first.
+- If `context --json-compact` (or `context --json`) returns `approvalRequest.required=true`, stop immediately and report to the user.
+- When `--start-auto` is used, prefer `autoRun.run.resumeCommand` (`flow --resume <runId>`) as the first resume path.
 
 ### GitHub helpers
 
@@ -578,7 +598,6 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
     - Use the `Pre-PR Baseline Checklist` section in `docs get create-pr --json` as the single source of truth
   - `evidenceMode` (optional): evidence validation mode (`"path_required"` | `"any"`, default: `"path_required"`)
     - `path_required`: evidence must be a real existing local path
-  - `findings` (optional): findings requirement (`"required"` | `"optional"`, default: `"required"`)
   - `decisionEnum` (optional): allowed decision outcomes (default: `["approve","changes_requested","blocked"]`)
     - Moving to PR step requires final decision `approve`
 - `workflow.auto`:
@@ -605,7 +624,6 @@ Example:
       "skills": ["code-review-excellence"],
       "fallback": "builtin-checklist",
       "evidenceMode": "path_required",
-      "findings": "required",
       "decisionEnum": ["approve", "changes_requested", "blocked"]
     }
   }

package/README.md

@@ -313,6 +313,7 @@ npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET> --execute-
 - `approvalRequest`: 승인 요청/실행에 바로 사용하는 안내 데이터 (`labels`, `approveCommand`, `executeCommand`, `options[]`)
 - `requiredDocs`: 현재 액션 전에 읽어야 할 CLI 내장 문서 목록 (`id`, `command`)
 - `checkPolicy`: 승인 검증 정책 (`token`, `acceptedTokens`, `tokenPattern`, `validLabels`, `contextVersion` 등)
+- `agentOrchestration`: 메인(대화/승인) + 서브(명령 실행) 역할 분리 계약 (`mode`, `delegationPolicy`, `delegateCommandExecution`, `longRunningCategories`, `fallbackToMainAgentWhenSubAgentUnavailable`, `pauseAndReportWhen`, `resumePriority`)
 
 **고급/참고 필드 (자동화 고급 시나리오 또는 디버깅용)**
 
@@ -382,8 +383,13 @@ npx lee-spec-kit flow F004 --request "issue 004를 F004로 승격시켜서 진
 # 기본 preset 설정 시 더 짧게 실행 가능
 npx lee-spec-kit flow F004 --request "issue 004를 F004로 승격시켜서 진행해"
 
+# 장시간 자동 진행: run 체크포인트 생성 + 재개
+npx lee-spec-kit flow F004 --auto-until-category pr_create,code_review,pr_status_update --start-auto --json-compact
+npx lee-spec-kit flow --resume <RUN_ID> --json-compact
+
 # 에이전트 파이프라인용 JSON
 npx lee-spec-kit flow --json
+npx lee-spec-kit flow --json-compact
 
 # 엄격 검사(선택)
 npx lee-spec-kit flow --strict
@@ -394,12 +400,15 @@ npx lee-spec-kit flow --strict
 | 옵션               | 설명 |
 | ------------------ | ---- |
 | `--json`           | 에이전트용 JSON 출력 |
+| `--json-compact`   | 에이전트용 압축 JSON 출력 (`--json` 포함, 중복 필드 최소화) |
 | `--component <id>` | multi에서 대상 컴포넌트 지정 (예: `app`, `api`, `worker`) |
 | `--all`            | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
 | `--done`           | 완료(workflow-done) Feature만 표시 |
 | `--request <text>` | auto 모드에서 새 사용자 요청을 먼저 반영 (`user_request_replan` 라벨 자동 선택) |
 | `--auto-preset <name>` | 이름 기반 auto preset 사용 (기본 제공: `pr-handoff`) |
 | `--auto-until-category <categories>` | command 액션을 자동 실행하다가 지정 category 중 하나가 나오면 중지 (쉼표 구분) |
+| `--start-auto`     | auto 실행 체크포인트(run id) 저장 후 JSON에 재개 정보(`autoRun.run`)를 함께 출력 |
+| `--resume <run-id>` | 저장된 auto 실행 체크포인트를 run id로 재개 |
 | `--approve <reply>`| context 라벨 승인 응답 전달 (예: `A`, `A OK`, `A 진행해`) |
 | `--execute`        | 승인한 옵션이 command일 때 실행 (`requiresUserCheck=true`면 티켓 연동, 아니면 티켓 없이 실행) |
 | `--execute-strict` | `--execute`와 함께 사용 시 instruction-only 옵션이면 실패 |
@@ -410,9 +419,20 @@ npx lee-spec-kit flow --strict
 - auto 모드(`--auto-until-category`/`--auto-preset`)는 `--approve`, `--execute`와 함께 사용할 수 없습니다.
 - `--request`는 auto 모드와 함께 사용해야 합니다.
   - 예외적으로 `workflow.auto.defaultPreset`이 설정되어 있으면 `--request`만으로도 auto 모드가 활성화됩니다.
+- `--resume <run-id>`는 `<feature-name>`, `--component`, `--all`, `--done`, `--auto-*`, `--request`와 함께 사용할 수 없습니다. (체크포인트에 저장된 설정을 사용)
 - 자동 진행은 지정한 category가 등장하면 `gate_reached`로 멈추고, 해당 단계의 승인 문구(`approvalRequest.userFacingLines`)를 그대로 출력합니다.
+- 현재 액션이 instruction-only라 command 자동 실행이 불가능하면 `AUTO_MANUAL_REQUIRED`로 멈출 수 있습니다. (CLI 오류가 아니라 자동화 경계 도달 상태)
 - 진행 정체(동일 context/action 반복)가 감지되면 `AUTO_NO_PROGRESS`로 중단됩니다.
-- JSON 모드에서는 `autoRun.status`, `autoRun.reasonCode`, `autoRun.gate`, `autoRun.executions`로 상세 상태를 확인할 수 있습니다.
+- JSON 모드에서는 `autoRun.status`, `autoRun.reasonCode`, `autoRun.gate`, `autoRun.executions`, `autoRun.resume`로 상세 상태를 확인할 수 있습니다.
+- JSON `agentOrchestration`으로 메인/서브 에이전트 역할 및 중단/보고 조건을 확인할 수 있습니다.
+  - `delegateCommandExecution: "long_running_only"`면 짧은 단계는 메인이 처리하고, `longRunningCategories`에 해당하는 장시간 루프만 서브 에이전트 위임을 권장합니다.
+- `--start-auto`를 사용하면 JSON `autoRun.run`에 `runId`, `status`, `resumeCommand`가 포함됩니다.
+
+에이전트 재개 규칙(권장):
+- `flow --json-compact`(또는 `flow --json`) 결과에 `autoRun.enabled=true`가 있으면, 중단/압축 후에도 `autoRun.resume.flowCommand`를 그대로 재실행해 이어갑니다.
+- 재개 전 현재 지점 확인이 필요하면 `autoRun.resume.contextCommand`를 먼저 실행합니다.
+- `context --json-compact`(또는 `context --json`) 확인 결과 `approvalRequest.required=true`면 즉시 멈추고 사용자에게 보고합니다.
+- `--start-auto`를 사용하는 경우에는 `autoRun.run.resumeCommand`(`flow --resume <runId>`)를 우선 재개 경로로 사용합니다.
 
 ### GitHub helper
 
@@ -626,7 +646,6 @@ npx lee-spec-kit update --force
     - 상세 기준은 `docs get create-pr --json`의 `Pre-PR 기본 체크리스트` 섹션을 단일 기준으로 사용
   - `evidenceMode` (선택): Evidence 검증 방식 (`"path_required"` | `"any"`, 기본: `"path_required"`)
     - `path_required`: 실제 존재하는 로컬 경로만 인정
-  - `findings` (선택): Findings 필수 여부 (`"required"` | `"optional"`, 기본: `"required"`)
   - `decisionEnum` (선택): 허용 Decision 값 목록 (기본: `["approve","changes_requested","blocked"]`)
     - PR 단계로 진행하려면 최종 Decision이 `approve`여야 함
 - `workflow.auto`:
@@ -653,7 +672,6 @@ npx lee-spec-kit update --force
       "skills": ["code-review-excellence"],
       "fallback": "builtin-checklist",
       "evidenceMode": "path_required",
-      "findings": "required",
       "decisionEnum": ["approve", "changes_requested", "blocked"]
     }
   }