lee-spec-kit 0.6.37 → 0.6.38

package/README.en.md

@@ -294,7 +294,8 @@ 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`)
+- `agentOrchestration`: main-agent (conversation/approval) + sub-agent (execution) contract. The current SSOT is `subAgentHandoff` plus `matchedFeature.currentSubstate*`; `delegateCommandExecution`, `longRunningCategories`, and `currentActionShouldDelegate` are compatibility fields.
+- `matchedFeature.currentSubstateId/currentSubstateOwner/currentSubstatePhase`: current step-internal execution state for owner/phase-aware orchestration
 
 **Advanced/reference fields (automation edge cases or debugging)**
 
@@ -405,8 +406,8 @@ Auto gate mode rules:
 - 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`, `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`.
+- Inspect JSON `agentOrchestration` and `matchedFeature.currentSubstate*` for main/sub-agent responsibilities and pause/report boundaries.
+  - Prefer `matchedFeature.currentSubstateOwner` plus `subAgentHandoff` as the delegation signal when present. `longRunningCategories` and `currentActionShouldDelegate` remain legacy compatibility metadata for older non-substate paths.
 - With `--start-auto`, JSON also includes `autoRun.run` (`runId`, `status`, `resumeCommand`).
 
 Agent resume rules (recommended):
@@ -464,6 +465,35 @@ Status values distinguish implementation vs workflow completion:
 - `DONE`: all tasks are marked done, but workflow requirements are not fully satisfied
 - `WORKFLOW_DONE`: implementation + workflow requirements are both satisfied
 
+### PRD Requirement Traceability
+
+Aggregate PRD coverage from PRD requirement IDs (e.g. `PRD-FR-001`) and Feature `tasks.md` bracket tags (e.g. `[PRD-FR-001]`).
+
+Recommended SSOT:
+- PRD (`docs/prd/`): requirements SSOT (keep stable IDs)
+- Ideas (`docs/ideas/`): pre-Feature stage (record `PRD Refs` at the top)
+- Features (`docs/features/`): implementation/progress SSOT (`PRD Refs` in `spec.md`, task tags in `tasks.md`, change records in `decisions.md`)
+
+When requirements/scope change mid-work, update at minimum:
+- PRD docs + `spec.md` `PRD Refs` + `tasks.md` task tags
+- (when applicable) `plan.md`, `decisions.md`
+
+```bash
+npx lee-spec-kit requirements
+
+# alias
+npx lee-spec-kit prd
+
+# JSON output for agents
+npx lee-spec-kit requirements --json
+
+# Write report (docs/prd/status.md)
+npx lee-spec-kit requirements --write
+
+# Exit code 1 when issues exist (unknown refs / unmapped tasks / untracked requirements)
+npx lee-spec-kit requirements --strict --json
+```
+
 ### Global Option
 
 ```bash
@@ -527,7 +557,7 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
     "taskCommitGate": "warn",
     "prePrReview": {
       "skills": ["code-review-excellence"],
-      "enforceExecutionEvidence": true
+      "enforceExecutionEvidence": false
     }
   },
   "pr": { "screenshots": { "upload": false } },
@@ -603,9 +633,10 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
     - `path_required`: evidence must be a real existing local path
   - `decisionEnum` (optional): allowed decision outcomes (default: `["approve","changes_requested","blocked"]`)
     - Moving to PR step requires final decision `approve`
-  - `enforceExecutionEvidence` (optional): require proof that a review agent was actually executed (default: `true`)
+  - `enforceExecutionEvidence` (optional): require proof that a review agent was actually executed (default: `false`)
     - when `true`, `pre-pr-review` requires `--evidence` and non-empty `commandsExecuted`
-  - `executionCommandPrefixes` (optional): command prefixes to match against `commandsExecuted` (default: `[]`)
+    - when `false`, implementation-quality review fields remain required, while `commandsExecuted` is optional review evidence
+  - `executionCommandPrefixes` (optional): command prefixes to match against `commandsExecuted` when execution evidence is enforced (default: `[]`)
     - when non-empty, at least one executed command must start with one of these prefixes
 - `workflow.auto`:
   - `defaultPreset` (optional): default auto preset used by `flow --request "<text>"` (default: `"pr-handoff"`)
@@ -632,7 +663,7 @@ Example:
       "fallback": "builtin-checklist",
       "evidenceMode": "path_required",
       "decisionEnum": ["approve", "changes_requested", "blocked"],
-      "enforceExecutionEvidence": true,
+      "enforceExecutionEvidence": false,
       "executionCommandPrefixes": []
     }
   }
@@ -658,9 +689,9 @@ Pre-PR execution gate risks and mitigations:
 - `requireCheckCategories` (`category` only): categories that **always** require CHECK (e.g. `["pr_create"]`, `["*"]`)
 - `skipCheckCategories` (`category` only): categories that **never** require CHECK (e.g. `["docs_commit"]`, `["*"]`)
 - `requireCheckSteps` (`steps` only): step numbers that require CHECK (e.g. `[3, 5, 12]`)
-- `taskExecuteCheck` (optional): `task_execute` approval policy (`both` | `start_only`, default: `both`)
-  - `both`: require approval for both TODO→DOING and DOING→DONE transitions
-  - `start_only`: require approval only for TODO→DOING, skip default approval for DOING→DONE
+- `taskExecuteCheck` (optional): legacy `task_execute` start/complete phase compatibility override (`both` | `start_only`, default: `both`)
+  - `both`: on legacy `task_execute` compatibility paths, require approval for both TODO→DOING and DOING→DONE transitions
+  - `start_only`: on legacy `task_execute` compatibility paths, require approval only for TODO→DOING and skip default approval for DOING→DONE
 
 #### category examples
 

package/README.md

@@ -313,7 +313,8 @@ 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`)
+- `agentOrchestration`: 메인(대화/승인) + 서브(명령 실행) 역할 분리 계약. 현재 SSOT는 `subAgentHandoff`와 `matchedFeature.currentSubstate*`이며, `delegateCommandExecution`/`longRunningCategories`/`currentActionShouldDelegate`는 compatibility field입니다.
+- `matchedFeature.currentSubstateId/currentSubstateOwner/currentSubstatePhase`: step 내부 실행 상태와 owner/phase 기반 오케스트레이션 판단용 필드
 
 **고급/참고 필드 (자동화 고급 시나리오 또는 디버깅용)**
 
@@ -424,8 +425,8 @@ npx lee-spec-kit flow --strict
 - 현재 액션이 instruction-only라 command 자동 실행이 불가능하면 `AUTO_MANUAL_REQUIRED`로 멈출 수 있습니다. (CLI 오류가 아니라 자동화 경계 도달 상태)
 - 진행 정체(동일 context/action 반복)가 감지되면 `AUTO_NO_PROGRESS`로 중단됩니다.
 - JSON 모드에서는 `autoRun.status`, `autoRun.reasonCode`, `autoRun.gate`, `autoRun.executions`, `autoRun.resume`로 상세 상태를 확인할 수 있습니다.
-- JSON `agentOrchestration`으로 메인/서브 에이전트 역할 및 중단/보고 조건을 확인할 수 있습니다.
-  - `delegateCommandExecution: "long_running_only"`면 짧은 단계는 메인이 처리하고, `longRunningCategories`에 해당하는 장시간 루프만 서브 에이전트 위임을 권장합니다.
+- JSON `agentOrchestration`과 `matchedFeature.currentSubstate*`로 메인/서브 에이전트 역할 및 중단/보고 조건을 확인할 수 있습니다.
+  - 위임 판단은 `matchedFeature.currentSubstateOwner`와 `subAgentHandoff`를 우선 사용하세요. `longRunningCategories`와 `currentActionShouldDelegate`는 substate가 없는 레거시 경로용 compatibility 메타데이터입니다.
 - `--start-auto`를 사용하면 JSON `autoRun.run`에 `runId`, `status`, `resumeCommand`가 포함됩니다.
 
 에이전트 재개 규칙(권장):
@@ -490,6 +491,36 @@ npx lee-spec-kit status --strict
 - `DONE`: 태스크는 모두 완료됐지만 워크플로우 요구사항이 완전히 충족되진 않음
 - `WORKFLOW_DONE`: 구현 + 워크플로우 요구사항까지 모두 충족
 
+### PRD 요구사항 추적
+
+PRD 요구사항 ID(`PRD-FR-001` 등)와 Feature `tasks.md` 태그(`[PRD-FR-001]`)를 기반으로 PRD 커버리지를 집계합니다.
+
+SSOT(단일 기준) 권장:
+- PRD(`docs/prd/`): 요구사항 SSOT (ID 안정성 유지)
+- Ideas(`docs/ideas/`): Feature 전 단계 (상단에 `PRD Refs` 기록)
+- Features(`docs/features/`): 구현/진행 SSOT (`spec.md`의 `PRD Refs`, `tasks.md`의 태스크 태그, `decisions.md`의 변경 기록)
+
+중간에 요구사항/범위가 바뀌면 최소 아래를 함께 갱신하세요:
+- PRD 문서 + `spec.md`의 `PRD Refs` + `tasks.md`의 태스크 태그
+- (필요 시) `plan.md`, `decisions.md`
+
+```bash
+# 터미널에 출력
+npx lee-spec-kit requirements
+
+# alias
+npx lee-spec-kit prd
+
+# 에이전트용 JSON 출력
+npx lee-spec-kit requirements --json
+
+# 파일로 저장 (docs/prd/status.md)
+npx lee-spec-kit requirements --write
+
+# 이슈가 있으면 종료 코드 1 (unknown refs / unmapped tasks / untracked requirements)
+npx lee-spec-kit requirements --strict --json
+```
+
 ### 공통 옵션
 
 ```bash
@@ -576,7 +607,7 @@ npx lee-spec-kit update --force
     "taskCommitGate": "warn",
     "prePrReview": {
       "skills": ["code-review-excellence"],
-      "enforceExecutionEvidence": true
+      "enforceExecutionEvidence": false
     }
   },
   "pr": { "screenshots": { "upload": false } },
@@ -651,9 +682,10 @@ npx lee-spec-kit update --force
     - `path_required`: 실제 존재하는 로컬 경로만 인정
   - `decisionEnum` (선택): 허용 Decision 값 목록 (기본: `["approve","changes_requested","blocked"]`)
     - PR 단계로 진행하려면 최종 Decision이 `approve`여야 함
-  - `enforceExecutionEvidence` (선택): 리뷰 에이전트 실제 실행 증거 강제 여부 (기본: `true`)
+  - `enforceExecutionEvidence` (선택): 리뷰 에이전트 실제 실행 증거 강제 여부 (기본: `false`)
     - `true`일 때 `pre-pr-review`는 `--evidence`와 비어있지 않은 `commandsExecuted`를 요구
-  - `executionCommandPrefixes` (선택): `commandsExecuted`와 매칭할 명령 prefix 목록 (기본: `[]`)
+    - `false`일 때도 구현 품질 리뷰 필드는 필수이며, `commandsExecuted`는 선택적 보조 evidence입니다
+  - `executionCommandPrefixes` (선택): 실행 증거를 강제할 때 `commandsExecuted`와 매칭할 명령 prefix 목록 (기본: `[]`)
     - 비어있지 않으면 실행 명령 중 최소 1개가 해당 prefix로 시작해야 함
 - `workflow.auto`:
   - `defaultPreset` (선택): `flow --request "<요청>"` 실행 시 기본으로 사용할 auto preset 이름 (기본: `"pr-handoff"`)
@@ -680,7 +712,7 @@ npx lee-spec-kit update --force
       "fallback": "builtin-checklist",
       "evidenceMode": "path_required",
       "decisionEnum": ["approve", "changes_requested", "blocked"],
-      "enforceExecutionEvidence": true,
+      "enforceExecutionEvidence": false,
       "executionCommandPrefixes": []
     }
   }
@@ -706,9 +738,9 @@ Pre-PR 실행 게이트 리스크와 완화:
 - `requireCheckCategories` (`category`만): 확인을 **항상** 요구할 category 목록 (예: `["pr_create"]`, `["*"]`)
 - `skipCheckCategories` (`category`만): 확인을 **절대** 요구하지 않을 category 목록 (예: `["docs_commit"]`, `["*"]`)
 - `requireCheckSteps` (`steps`만): 확인이 필요한 step 번호 목록 (예: `[3, 5, 12]`)
-- `taskExecuteCheck` (선택): `task_execute` 확인 정책 (`both` | `start_only`, 기본: `both`)
-  - `both`: TODO→DOING, DOING→DONE 모두 승인 필요
-  - `start_only`: TODO→DOING만 승인 필요, DOING→DONE은 기본 승인 생략
+- `taskExecuteCheck` (선택): 레거시 `task_execute` 시작/완료 phase 호환용 확인 정책 (`both` | `start_only`, 기본: `both`)
+  - `both`: 기존 `task_execute` 호환 경로에서 TODO→DOING, DOING→DONE 모두 승인 필요
+  - `start_only`: 기존 `task_execute` 호환 경로에서 TODO→DOING만 승인 필요, DOING→DONE은 기본 승인 생략
 
 #### category 예시