lee-spec-kit 0.6.7 → 0.6.8

package/README.en.md

@@ -115,9 +115,10 @@ npx lee-spec-kit init --name my-project --type fullstack  # alias
 | `--workflow <mode>` | Workflow mode: `github` (issue/PR/review) or `local` (local-first)                         | `github`                        |
 | `-d, --dir <dir>`   | Install directory                                                                           | `./docs`                        |
 | `--docs-repo <mode>` | docs repo mode (`embedded` or `standalone`)                                               | `embedded`                      |
-| `--project-root <path>` | standalone(single) project repo path                                                   | -                               |
+| `--project-root <path>` | standalone(single) project repo path or standalone(multi) JSON map (`{"fe":"/path/fe"}`) | -                               |
 | `--fe-project-root <path>` | standalone(multi) frontend repo path                                                | -                               |
 | `--be-project-root <path>` | standalone(multi) backend repo path                                                 | -                               |
+| `--component-project-roots <pairs>` | standalone(multi) component roots (`fe=/path/fe,be=/path/be,worker=/path/worker`) | - |
 | `--push-docs` | enable standalone docs push (use with `--docs-remote`)                                   | `false`                         |
 | `--docs-remote <url>` | standalone docs remote URL (used with `--push-docs`)                                    | -                               |
 | `-y, --yes`         | Skip most interactive inputs (overwrite confirmation still appears if target dir is not empty) | -                               |
@@ -126,6 +127,21 @@ npx lee-spec-kit init --name my-project --type fullstack  # alias
 
 > After generating docs, `init` automatically attempts Git setup/commit (`git init`, `git add`, `git commit`). Auto-commit may be skipped depending on environment/state.
 
+### Project detection (agent entrypoint)
+
+```bash
+# detect from current directory
+npx lee-spec-kit detect
+
+# JSON output for agents/automation
+npx lee-spec-kit detect --json
+
+# detect against a specific path
+npx lee-spec-kit detect --dir /path/to/workspace
+```
+
+The `--json` payload includes `isLeeSpecKitProject`, `reasonCode` (`PROJECT_DETECTED` | `PROJECT_NOT_DETECTED`), `docsDir`, `configPath`, and `detectionSource` (`config` | `heuristic`).
+
 ### Create a feature
 
 ```bash
@@ -133,8 +149,8 @@ npx lee-spec-kit init --name my-project --type fullstack  # alias
 npx lee-spec-kit feature user-auth
 
 # Multi
-npx lee-spec-kit feature --repo be user-auth
-npx lee-spec-kit feature --repo fe user-profile
+npx lee-spec-kit feature --component be user-auth
+npx lee-spec-kit feature --component fe user-profile
 npx lee-spec-kit feature --component worker queue-jobs
 
 # Specify Feature ID/description
@@ -145,7 +161,6 @@ npx lee-spec-kit feature payment --id F123 --desc "Improve payment flow"
 
 | Option              | Description                                 | Default      |
 | ------------------- | ------------------------------------------- | ------------ |
-| `-r, --repo <repo>` | Multi target component (backward-compatible alias) | interactive  |
 | `--component <id>`  | Multi target component                       | interactive  |
 | `--id <id>`         | Feature ID (`F001` format)                  | auto-generate |
 | `-d, --desc <desc>` | Default purpose/description text for `spec.md` | empty string |
@@ -157,60 +172,64 @@ npx lee-spec-kit feature payment --id F123 --desc "Improve payment flow"
 For a single matched feature, next steps are always shown as `A/B/C` options.
 
 ```bash
-# Auto-detect (based on git branch)
+# basic check (auto-detect from branch)
 npx lee-spec-kit context
 
-# Specify a feature
-npx lee-spec-kit context user-auth
-
-# Selector: Feature ID / folder name
+# recommended: one feature + labels
 npx lee-spec-kit context F001
-npx lee-spec-kit context F001-user-auth
-
-# multi component selector
-npx lee-spec-kit context --repo fe
-npx lee-spec-kit context --repo worker
-
-# include all / done features
-npx lee-spec-kit context --all
-npx lee-spec-kit context --done
-
-# JSON output (for agents)
-npx lee-spec-kit context --json
+npx lee-spec-kit context F001 --json
 
-# approve a labeled option (validation only)
-npx lee-spec-kit context F001 --approve A
+# approve + execute (common path)
+npx lee-spec-kit context F001 --approve A --execute
 
-# approve + execute exactly one command option
-npx lee-spec-kit context F001 --approve "A OK" --execute
+# include ticket only when selected action has `requiresUserCheck=true`
+npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET>
 
-# fail when the approved label is instruction-only
-npx lee-spec-kit context F001 --approve A --execute --execute-strict
+# strict mode: fail if approved label is instruction-only
+npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET> --execute-strict
 ```
 
+Use advanced selectors (`--component`, `--all`, `--done`) only when you need multi-scope filtering or exceptional fallback behavior.
+
 **Options:**
 
 | Option         | Description                                     |
 | -------------- | ----------------------------------------------- |
 | `--json`       | JSON output for agents                          |
-| `--repo <repo>`| Select target component in multi mode (e.g. `fe`, `be`, `worker`) |
+| `--component <id>` | Select target component in multi mode (e.g. `fe`, `be`, `worker`) |
 | `--all`        | Include completed features when auto-detecting  |
 | `--done`       | Show completed (workflow-done) features only    |
-| `--approve <reply>` | Approve one labeled option (`A` or `A OK`) |
-| `--execute`    | Execute only the approved option when it is a command |
+| `--approve <reply>` | Approve one labeled option using any reply that includes a label token (e.g. `A`, `A OK`, `A proceed`) |
+| `--ticket <token>` | One-time execution ticket from `--approve` (required when selected option has `requiresUserCheck=true`) |
+| `--execute`    | Execute only the approved option when it is a command (`--ticket` required only for check-required options) |
 | `--execute-strict` | With `--execute`, fail if the approved option is instruction-only |
 
-`--json` output includes:
+**What is a ticket (approval ticket)?**
+
+- A one-time execution token issued by the CLI when you approve a label via `--approve`.
+- `--ticket` is required for `--execute` only when the selected action has `requiresUserCheck=true`.
+- It is short-lived (5 minutes by default) and cannot be reused after one execution.
+
+`context --json` is organized into `actions` (atomic actions), `actionOptions` (label mapping), and top-level metadata.
+
+**Core fields (recommended for normal agent flows)**
+
+- `status` / `reasonCode`: current state and reason code
+- `actions[]`: atomic action list
+  - `type: "command"`: `scope` (project|docs), `cwd`, `cmd`, `category`, `operationType`, `requiresUserCheck`
+  - `type: "instruction"`: `message`, `category`, `operationType`, `requiresUserCheck`
+- `actionOptions[]`: `label` (`A`, `B`, `C`...) + target `action` + user-facing `summary` / `detail` / `approvalPrompt`
+- `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`, ...)
+
+**Advanced/reference fields (automation edge cases or debugging)**
 
-- `reasonCode`: status reason code (`SINGLE_MATCHED`, `MULTIPLE_ACTIVE_FEATURES`, etc.)
-- `operationType`: action nature (`local` | `remote` | `manual`)
-- `actionOptions`: maps labels to atomic actions plus `summary`/`approvalPrompt` for user-facing label explanation
-- `primaryActionLabel` / `primaryActionType` / `primaryActionCategory` / `primaryActionOperationType`: metadata for the first atomic action
 - `selectionFallback`: fallback used when branch auto-detection does not match (`none` | `open_features` | `all_features` | `done_features`)
+- `primaryActionLabel` / `primaryActionType` / `primaryActionCategory` / `primaryActionOperationType`: summary metadata for the first atomic action
 - `workflowPolicy`: current completion policy (`mode`, `requireIssue`, `requireBranch`, `requirePr`, `requireReview`)
+- `taskCommitGatePolicy`: task commit gate policy (`off` | `warn` | `strict`)
 - `prePrReviewPolicy`: pre-PR review policy (`enabled`, `skills`, `fallback`, `blockOnFindings`)
-- `requiredDocs`: CLI built-in docs to read before the current action (`id`, `command`)
-- `checkPolicy`: approval validation policy (`hint`, `policyOnly`, `token: "<LABEL>"`, `acceptedTokens`, `tokenPattern`, `validLabels`, `requireExplanationBeforeApproval`, `requiredExplanationFields`, `contextVersion`, ...)
 
 Error payloads (`status: "error"`) include `reasonCode` and labeled `suggestions` (`A/B/C`) (e.g. `INVALID_APPROVAL`, `CONTEXT_STALE`, `EXECUTION_FAILED`, `EXECUTION_NOT_COMMAND`).
 
@@ -247,18 +266,24 @@ npx lee-spec-kit view --json
 | Option         | Description                                     |
 | -------------- | ----------------------------------------------- |
 | `--json`       | JSON output for agents                          |
-| `--repo <repo>`| Select target component in multi mode (e.g. `fe`, `be`, `worker`) |
+| `--component <id>` | Select target component in multi mode (e.g. `fe`, `be`, `worker`) |
 | `--all`        | Include completed features when auto-detecting  |
 | `--done`       | Show completed (workflow-done) features only    |
 
 ### Flow
 
 ```bash
+# workflow summary (context + status + doctor)
 npx lee-spec-kit flow
-npx lee-spec-kit flow F001 --approve A
-npx lee-spec-kit flow F001 --approve "A OK" --execute
-npx lee-spec-kit flow --strict
+
+# approve + execute (recommended agent path)
+npx lee-spec-kit flow F001 --approve A --execute
+
+# JSON output for automation
 npx lee-spec-kit flow --json
+
+# strict checks (optional)
+npx lee-spec-kit flow --strict
 ```
 
 **Options:**
@@ -266,11 +291,11 @@ npx lee-spec-kit flow --json
 | Option            | Description |
 | ----------------- | ----------- |
 | `--json`          | JSON output for agents |
-| `--repo <repo>`   | Select target component in multi mode (e.g. `fe`, `be`, `worker`) |
+| `--component <id>`| Select target component in multi mode (e.g. `fe`, `be`, `worker`) |
 | `--all`           | Include completed features when auto-detecting |
 | `--done`          | Show completed (workflow-done) features only |
-| `--approve <reply>` | Pass through context label approval (`A` or `A OK`) |
-| `--execute`       | Execute approved option when it is a command |
+| `--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 |
 | `--strict`        | Also run `status --strict` and `doctor --strict` |
 
@@ -353,6 +378,7 @@ npx lee-spec-kit doctor --decisions-placeholders warn
 
 By default, `update` runs only when the `docs/` working tree is clean; in that case it overwrites changed files without prompting.  
 If you want to update while you have uncommitted changes, use `--force`.
+`update` also backfills missing `.lee-spec-kit.json` keys using current defaults (e.g. `workflow.taskCommitGate: "strict"`).
 
 ```bash
 npx lee-spec-kit update
@@ -381,6 +407,7 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
   "workflow": {
     "mode": "github",
     "codeDirtyScope": "auto",
+    "taskCommitGate": "strict",
     "prePrReview": { "skills": ["code-review-excellence"] }
   },
   "pr": { "screenshots": { "upload": false } },
@@ -399,7 +426,7 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
 | `pushDocs`    | (standalone only) whether to manage/push docs repo as a separate git repo |
 | `docsRemote`  | (standalone + pushDocs) docs repo remote URL |
 | `projectRoot` | (standalone only) project repo path (single: string, multi: `{ [component]: path }`) |
-| `workflow`    | (optional) workflow completion policy (`github`/`local`, `codeDirtyScope`, `prePrReview`) |
+| `workflow`    | (optional) workflow completion policy (`github`/`local`, `codeDirtyScope`, `taskCommitGate`, `prePrReview`) |
 | `pr`          | (optional) PR artifacts policy (e.g. screenshot upload) |
 | `approval`    | (optional) Override CHECK-required policy in `context` output (for automation/semi-auto) |
 
@@ -413,14 +440,15 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
 - the `[CHECK required]` tag in text output
 - `actions[].requiresUserCheck` in `context --json`
 - `checkPolicy.token` (`context --json`): approval token format (`<LABEL>`)
-- `checkPolicy.acceptedTokens`: accepted reply templates (e.g. `["<LABEL>", "<LABEL> OK"]`)
+- `checkPolicy.acceptedTokens`: accepted reply templates (e.g. `["<LABEL>", "<LABEL> OK", "<LABEL> ...", "... <LABEL> ..."]`)
 - `checkPolicy.tokenPattern`: input validation regex for approval replies
 - `checkPolicy.validLabels`: currently selectable labels (`A`, `B`, `C`...)
 - `checkPolicy.requireExplanationBeforeApproval`: require label-by-label explanation before asking approval
-- `checkPolicy.requiredExplanationFields`: fields to use for explanation (e.g. `actionOptions[].summary`)
+- `checkPolicy.requiredExplanationFields`: fields to use for explanation (e.g. `actionOptions[].detail`)
 - `checkPolicy.contextVersion`: snapshot hash for stale-context validation
 - `actionOptions`: maps `label` (`A`, `B`, `C`...) to each atomic `action`
 - `workflowPolicy`: current completion policy (`mode`, `requireIssue`, `requireBranch`, `requirePr`, `requireReview`)
+- `taskCommitGatePolicy`: task commit gate policy (`off` | `warn` | `strict`)
 
 > This does not enforce/deny execution by itself; it’s a signal for agents.
 > If `approval` is omitted, it behaves as `builtin`. (No migration required)
@@ -437,6 +465,11 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
   - `auto`: `single => repo`, `multi => component`
   - `workflow.componentPaths` (optional): explicit per-component paths for component-scoped checks (e.g. `"web": ["apps/web", "packages/web-ui"]`)
   - backward compatibility: if omitted, runtime defaults to `repo`
+- `workflow.taskCommitGate`:
+  - `strict`: block moving to next TODO when the `1 task = 1 commit` check fails
+  - `warn`: show warning but allow progress
+  - `off`: disable the check
+  - backward compatibility: if omitted, runtime defaults to `warn`
 - `workflow.prePrReview`:
   - `enabled` (optional): enforce pre-PR review stage (default: same as `requirePr`)
   - `skills` (optional): preferred skill names in priority order (default: `["code-review-excellence"]`)
@@ -450,6 +483,7 @@ Example:
   "workflow": {
     "mode": "github",
     "codeDirtyScope": "auto",
+    "taskCommitGate": "strict",
     "prePrReview": {
       "skills": ["code-review-excellence"],
       "fallback": "builtin-checklist",
@@ -510,12 +544,12 @@ npx lee-spec-kit config --project-root /new/path
 npx lee-spec-kit config --dir ./docs2 --project-root /new/path
 
 # update projectRoot (multi)
-npx lee-spec-kit config --project-root /new/fe/path --repo fe
-npx lee-spec-kit config --project-root /new/be/path --repo be
+npx lee-spec-kit config --project-root /new/fe/path --component fe
+npx lee-spec-kit config --project-root /new/be/path --component be
 npx lee-spec-kit config --project-root /new/worker/path --component worker
 
 # non-interactive mode (fails immediately if required input is missing)
-npx lee-spec-kit config --project-root /new/fe/path --repo fe --non-interactive
+npx lee-spec-kit config --project-root /new/fe/path --component fe --non-interactive
 ```
 
 **Options:**
@@ -524,7 +558,6 @@ npx lee-spec-kit config --project-root /new/fe/path --repo fe --non-interactive
 | --- | --- |
 | `--dir <dir>` | Target docs directory or project path |
 | `--project-root <path>` | Set projectRoot path |
-| `--repo <repo>` | Target component in multi mode (backward-compatible alias) |
 | `--component <id>` | Target component in multi mode |
 | `--non-interactive` | Fail immediately instead of prompting for user input |
 

package/README.md

@@ -131,9 +131,10 @@ npx lee-spec-kit init --name my-project --type fullstack  # alias
 | `--workflow <mode>` | 워크플로우 모드: `github`(issue/PR/review 포함) 또는 `local`(로컬 중심) | `github`                  |
 | `-d, --dir <dir>`   | 설치 디렉토리                                                        | `./docs`                  |
 | `--docs-repo <mode>` | docs 레포 모드 (`embedded` 또는 `standalone`)                        | `embedded`                |
-| `--project-root <path>` | standalone(single) 프로젝트 레포 경로                              | -                         |
+| `--project-root <path>` | standalone(single) 프로젝트 레포 경로 또는 standalone(multi) JSON 매핑 (`{"fe":"/path/fe"}`) | -                         |
 | `--fe-project-root <path>` | standalone(multi) FE 레포 경로                                  | -                         |
 | `--be-project-root <path>` | standalone(multi) BE 레포 경로                                  | -                         |
+| `--component-project-roots <pairs>` | standalone(multi) 컴포넌트별 레포 경로 (`fe=/path/fe,be=/path/be,worker=/path/worker`) | - |
 | `--push-docs` | standalone docs 원격 push 사용 (`--docs-remote`와 함께 사용)     | `false`                   |
 | `--docs-remote <url>` | standalone docs 원격 URL (`--push-docs`와 함께 사용)              | -                         |
 | `-y, --yes`         | 대화형 입력을 대부분 스킵 (단, 대상 디렉토리가 비어있지 않으면 덮어쓰기 확인은 표시) | -                         |
@@ -142,6 +143,21 @@ npx lee-spec-kit init --name my-project --type fullstack  # alias
 
 > `init`은 docs 생성 후 Git 초기화/커밋(`git init`, `git add`, `git commit`)을 자동 시도합니다. 환경에 따라 자동 커밋이 생략될 수 있습니다.
 
+### 프로젝트 감지 (에이전트 시작점)
+
+```bash
+# 현재 경로 기준 감지
+npx lee-spec-kit detect
+
+# 에이전트/자동화용 JSON
+npx lee-spec-kit detect --json
+
+# 특정 경로 기준 감지
+npx lee-spec-kit detect --dir /path/to/workspace
+```
+
+`--json` 출력은 `isLeeSpecKitProject`, `reasonCode`(`PROJECT_DETECTED` | `PROJECT_NOT_DETECTED`), `docsDir`, `configPath`, `detectionSource`(`config` | `heuristic`)를 포함합니다.
+
 ### 새 기능 생성
 
 ```bash
@@ -149,8 +165,8 @@ npx lee-spec-kit init --name my-project --type fullstack  # alias
 npx lee-spec-kit feature user-auth
 
 # Multi 프로젝트
-npx lee-spec-kit feature --repo be user-auth
-npx lee-spec-kit feature --repo fe user-profile
+npx lee-spec-kit feature --component be user-auth
+npx lee-spec-kit feature --component fe user-profile
 npx lee-spec-kit feature --component worker queue-jobs
 
 # Feature ID/설명 지정
@@ -161,7 +177,6 @@ npx lee-spec-kit feature payment --id F123 --desc "결제 플로우 개선"
 
 | 옵션                | 설명                                         | 기본값      |
 | ------------------- | -------------------------------------------- | ----------- |
-| `-r, --repo <repo>` | multi 대상 컴포넌트 (하위호환 alias)          | 대화형 선택 |
 | `--component <id>`  | multi 대상 컴포넌트                           | 대화형 선택 |
 | `--id <id>`         | Feature ID (`F001` 형식)                     | 자동 생성   |
 | `-d, --desc <desc>` | `spec.md`의 목적(설명) 기본 문구             | 빈 문자열   |
@@ -174,65 +189,64 @@ npx lee-spec-kit feature payment --id F123 --desc "결제 플로우 개선"
 단일 Feature 상세에서는 다음 작업을 항상 `A/B/C` 옵션으로 표시합니다.
 
 ```bash
-# 자동 감지 (Git 브랜치 기준)
+# 기본 조회 (브랜치 기준 자동 감지)
 npx lee-spec-kit context
 
-# 특정 Feature 지정
-npx lee-spec-kit context user-auth
-
-# selector 지원: Feature ID / 폴더명
+# 특정 Feature 상태 + 라벨 확인 (에이전트 권장)
 npx lee-spec-kit context F001
-npx lee-spec-kit context F001-user-auth
-
-# multi에서 컴포넌트 지정
-npx lee-spec-kit context --repo fe
-npx lee-spec-kit context --repo worker
-
-# 전체/완료 Feature 포함
-npx lee-spec-kit context --all
-npx lee-spec-kit context --done
+npx lee-spec-kit context F001 --json
 
-# 에이전트용 JSON 출력
-npx lee-spec-kit context --json
-
-# 라벨 승인 선택 (검증만)
-npx lee-spec-kit context F001 --approve A
+# 승인 + 실행 (일반 케이스)
+npx lee-spec-kit context F001 --approve A --execute
 
-# 라벨 승인 + 단일 명령 실행
-npx lee-spec-kit context F001 --approve "A OK" --execute
+# 선택된 액션이 `requiresUserCheck=true`일 때만 티켓 포함
+npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET>
 
-# 승인 라벨이 instruction-only면 실패 처리
-npx lee-spec-kit context F001 --approve A --execute --execute-strict
+# 엄격 실행 모드 (instruction-only 라벨이면 실패)
+npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET> --execute-strict
 ```
 
+고급 선택자(`--component`, `--all`, `--done`)는 multi 범위 제어나 예외 상황에서만 사용하세요.
+
 **옵션:**
 
 | 옵션            | 설명                                            |
 | --------------- | ----------------------------------------------- |
 | `--json`        | 에이전트용 JSON 출력                            |
-| `--repo <repo>` | multi에서 대상 컴포넌트 지정 (예: `fe`, `be`, `worker`) |
+| `--component <id>` | multi에서 대상 컴포넌트 지정 (예: `fe`, `be`, `worker`) |
 | `--all`         | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
 | `--done`        | 완료(workflow-done) Feature만 표시              |
-| `--approve <reply>` | 라벨 승인 응답 (`A` 또는 `A OK`)으로 단일 옵션 선택 |
-| `--execute`     | `--approve`로 선택한 옵션이 command일 때 1개만 실행 |
+| `--approve <reply>` | 라벨 포함 승인 응답으로 단일 옵션 선택 (예: `A`, `A OK`, `A 진행해`) |
+| `--ticket <token>` | `--approve` 결과에서 받은 1회용 실행 티켓 (`requiresUserCheck=true` 옵션에서 필요) |
+| `--execute`     | 승인된 command 옵션 1개만 실행 (`requiresUserCheck=true`면 `--ticket` 필요) |
 | `--execute-strict` | `--execute`와 함께 사용 시 instruction-only 옵션이면 실패 |
 
-`--json` 출력에는 다음 액션이 `actions` 배열로 포함됩니다.
+**티켓(approval ticket)이란?**
+
+- `--approve`로 라벨을 승인할 때 CLI가 발급하는 1회용 실행 토큰입니다.
+- 선택한 액션이 `requiresUserCheck=true`인 경우에만 `--execute`에서 `--ticket`이 필요합니다.
+- 발급 후 짧은 시간(기본 5분)만 유효하며, 한 번 사용하면 재사용할 수 없습니다.
+
+`context --json` 출력은 크게 `actions`(원자 액션), `actionOptions`(라벨 매핑), 상위 메타데이터로 구성됩니다.
+
+**핵심 필드 (실사용 권장)**
+
+- `status`/`reasonCode`: 현재 상태와 이유 코드
+- `actions[]`: 원자 액션 목록
+  - `type: "command"`: `scope`(project|docs), `cwd`, `cmd`, `category`, `operationType`, `requiresUserCheck`
+  - `type: "instruction"`: `message`, `category`, `operationType`, `requiresUserCheck`
+- `actionOptions[]`: `label`(`A`, `B`, `C`...) + 실행 대상 `action` + 사용자 안내용 `summary`/`detail`/`approvalPrompt`
+- `approvalRequest`: 승인 요청/실행에 바로 사용하는 안내 데이터 (`labels`, `approveCommand`, `executeCommand`, `options[]`)
+- `requiredDocs`: 현재 액션 전에 읽어야 할 CLI 내장 문서 목록 (`id`, `command`)
+- `checkPolicy`: 승인 검증 정책 (`token`, `acceptedTokens`, `tokenPattern`, `validLabels`, `contextVersion` 등)
+
+**고급/참고 필드 (자동화 고급 시나리오 또는 디버깅용)**
 
-- `reasonCode`: 상태 이유 코드 (`SINGLE_MATCHED`, `MULTIPLE_ACTIVE_FEATURES` 등)
-- `type: "command"`: `scope`(project|docs), `cwd`, `cmd` 제공 (복사하여 붙여넣기 가능한 형태로 `cd ... && git ...` 형태로 출력)
-- `type: "instruction"`: 사람이 수행해야 하는 안내 메시지
-- `operationType`: 액션 성격 (`local` | `remote` | `manual`)
-- `actionOptions`: `label`(`A`, `B`, `C`...)과 해당 `action` 매핑 + `summary`/`approvalPrompt`(라벨 설명 템플릿)
-- `primaryActionLabel`/`primaryActionType`/`primaryActionCategory`/`primaryActionOperationType`: 첫 번째 원자 액션의 요약 메타데이터
 - `selectionFallback`: 자동 감지 실패 시 사용된 폴백 (`none` | `open_features` | `all_features` | `done_features`)
-- `category`: 액션 분류 (자동화/반자동용 `approval.mode: "category"`에서 사용)
-- `requiresUserCheck`: 사용자 확인 필요 여부 (에이전트는 **사용자 응답을 `<라벨>` 또는 `<라벨> OK` 형식(예: `A`, `A OK`)으로 제한**하는 것을 권장 / 설정의 `approval`로 오버라이드 가능)
+- `primaryActionLabel`/`primaryActionType`/`primaryActionCategory`/`primaryActionOperationType`: 첫 번째 원자 액션 요약 메타데이터
 - `workflowPolicy`: 현재 완료 조건 정책 (`mode`, `requireIssue`, `requireBranch`, `requirePr`, `requireReview`)
+- `taskCommitGatePolicy`: 태스크 커밋 게이트 정책 (`off` | `warn` | `strict`)
 - `prePrReviewPolicy`: pre-PR 리뷰 정책 (`enabled`, `skills`, `fallback`, `blockOnFindings`)
-- `requiredDocs`: 현재 액션 전에 읽어야 할 CLI 내장 문서 목록 (`id`, `command`)
-
-또한 `checkPolicy`가 포함되어, 에이전트가 사용자 확인 정책을 적용할 때 참고할 수 있습니다. (`docPath`, `hint`, `policyOnly`, `token: "<LABEL>"`, `acceptedTokens`, `tokenPattern`, `validLabels`, `requireExplanationBeforeApproval`, `requiredExplanationFields`, `contextVersion`, `config`)
 
 오류 응답(`status: "error"`)에는 `reasonCode`와 `suggestions`(라벨형 다음 동작: `A/B/C`)가 포함됩니다. (예: `INVALID_APPROVAL`, `CONTEXT_STALE`, `EXECUTION_FAILED`, `EXECUTION_NOT_COMMAND`)
 
@@ -269,18 +283,24 @@ npx lee-spec-kit view --json
 | 옵션            | 설명                                            |
 | --------------- | ----------------------------------------------- |
 | `--json`        | 에이전트용 JSON 출력                            |
-| `--repo <repo>` | multi에서 대상 컴포넌트 지정 (예: `fe`, `be`, `worker`) |
+| `--component <id>` | multi에서 대상 컴포넌트 지정 (예: `fe`, `be`, `worker`) |
 | `--all`         | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
 | `--done`        | 완료(workflow-done) Feature만 표시              |
 
 ### Flow 오케스트레이션
 
 ```bash
+# 워크플로우 요약 (context + status + doctor)
 npx lee-spec-kit flow
-npx lee-spec-kit flow F001 --approve A
-npx lee-spec-kit flow F001 --approve "A OK" --execute
-npx lee-spec-kit flow --strict
+
+# 승인 + 실행 (에이전트 기본 실행 경로)
+npx lee-spec-kit flow F001 --approve A --execute
+
+# 에이전트 파이프라인용 JSON
 npx lee-spec-kit flow --json
+
+# 엄격 검사(선택)
+npx lee-spec-kit flow --strict
 ```
 
 **옵션:**
@@ -288,11 +308,11 @@ npx lee-spec-kit flow --json
 | 옵션               | 설명 |
 | ------------------ | ---- |
 | `--json`           | 에이전트용 JSON 출력 |
-| `--repo <repo>`    | multi에서 대상 컴포넌트 지정 (예: `fe`, `be`, `worker`) |
+| `--component <id>` | multi에서 대상 컴포넌트 지정 (예: `fe`, `be`, `worker`) |
 | `--all`            | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
 | `--done`           | 완료(workflow-done) Feature만 표시 |
-| `--approve <reply>`| context 라벨 승인 응답 전달 (`A` 또는 `A OK`) |
-| `--execute`        | 승인한 옵션이 command일 때 실행 |
+| `--approve <reply>`| context 라벨 승인 응답 전달 (예: `A`, `A OK`, `A 진행해`) |
+| `--execute`        | 승인한 옵션이 command일 때 실행 (`requiresUserCheck=true`면 티켓 연동, 아니면 티켓 없이 실행) |
 | `--execute-strict` | `--execute`와 함께 사용 시 instruction-only 옵션이면 실패 |
 | `--strict`         | `status --strict`, `doctor --strict`까지 함께 검사 |
 
@@ -396,6 +416,7 @@ npx lee-spec-kit doctor --decisions-placeholders warn
 
 기본 동작은 `docs/` 작업트리에 변경사항이 없을 때만 업데이트를 진행하며, 이 경우 변경된 파일은 확인 없이 덮어씁니다.  
 변경사항이 있는 상태에서 업데이트하려면 `--force`를 사용하세요.
+또한 `update`는 `.lee-spec-kit.json`의 누락 필드를 현재 기본 정책으로 보강합니다. (예: `workflow.taskCommitGate: "strict"`)
 
 ```bash
 # 전체 업데이트
@@ -433,6 +454,7 @@ npx lee-spec-kit update --force
   "workflow": {
     "mode": "github",
     "codeDirtyScope": "auto",
+    "taskCommitGate": "strict",
     "prePrReview": { "skills": ["code-review-excellence"] }
   },
   "pr": { "screenshots": { "upload": false } },
@@ -451,7 +473,7 @@ npx lee-spec-kit update --force
 | `pushDocs`    | (standalone만) docs 레포를 별도 Git으로 관리/푸시할지 여부 |
 | `docsRemote`  | (standalone+pushDocs) docs 레포 remote URL |
 | `projectRoot` | (standalone만) 프로젝트 레포지토리 경로 (single: string, multi: `{ [component]: path }`) |
-| `workflow`    | (선택) 워크플로우 요구사항 정책 (`github`/`local`, `codeDirtyScope`, `prePrReview`) |
+| `workflow`    | (선택) 워크플로우 요구사항 정책 (`github`/`local`, `codeDirtyScope`, `taskCommitGate`, `prePrReview`) |
 | `pr`          | (선택) PR 결과물 정책 (예: 스크린샷 업로드 여부) |
 | `approval`    | (선택) `context` 출력의 `[확인 필요]`/`requiresUserCheck` 정책 오버라이드 (자동화/반자동용) |
 
@@ -467,11 +489,11 @@ npx lee-spec-kit update --force
 - 텍스트 출력의 `[확인 필요]` 표시
 - `context --json`의 `actions[].requiresUserCheck`
 - `checkPolicy.token` (`context --json`): 승인 토큰 형식 (`<LABEL>`)
-- `checkPolicy.acceptedTokens`: 허용되는 승인 응답 템플릿 (예: `["<LABEL>", "<LABEL> OK"]`)
+- `checkPolicy.acceptedTokens`: 허용되는 승인 응답 템플릿 (예: `["<LABEL>", "<LABEL> OK", "<LABEL> ...", "... <LABEL> ..."]`)
 - `checkPolicy.tokenPattern`: 승인 응답 검증용 정규식
 - `checkPolicy.validLabels`: 현재 선택 가능한 라벨 목록 (`A`, `B`, `C`...)
 - `checkPolicy.requireExplanationBeforeApproval`: 승인 요청 전에 라벨별 설명을 포함해야 함
-- `checkPolicy.requiredExplanationFields`: 라벨 설명에 사용할 필드 목록 (예: `actionOptions[].summary`)
+- `checkPolicy.requiredExplanationFields`: 라벨 설명에 사용할 필드 목록 (예: `actionOptions[].detail`)
 - `checkPolicy.contextVersion`: stale context 검증용 스냅샷 해시
 
 > 실제 명령 실행을 강제/차단하는 기능은 아닙니다. (에이전트가 참고하도록 신호를 제공)
@@ -489,6 +511,11 @@ npx lee-spec-kit update --force
   - `auto`: `single => repo`, `multi => component`
   - `workflow.componentPaths`(선택): component 판정 경로를 컴포넌트별로 명시 (예: `"web": ["apps/web", "packages/web-ui"]`)
   - 하위 호환: 값이 없으면 기존 동작인 `repo`로 처리
+- `workflow.taskCommitGate`:
+  - `strict`: 다음 TODO로 넘어가기 전에 `1 태스크 = 1 커밋` 점검 실패 시 차단
+  - `warn`: 점검 실패 시 경고만 표시하고 진행 허용
+  - `off`: 점검 비활성화
+  - 하위 호환: 값이 없으면 `warn`으로 처리
 - `workflow.prePrReview`:
   - `enabled` (선택): pre-PR 리뷰 단계를 강제할지 여부 (기본: `requirePr`와 동일)
   - `skills` (선택): 우선순위 스킬 목록 (기본: `["code-review-excellence"]`)
@@ -502,6 +529,7 @@ npx lee-spec-kit update --force
   "workflow": {
     "mode": "github",
     "codeDirtyScope": "auto",
+    "taskCommitGate": "strict",
     "prePrReview": {
       "skills": ["code-review-excellence"],
       "fallback": "builtin-checklist",
@@ -595,12 +623,12 @@ npx lee-spec-kit config --project-root /new/path
 npx lee-spec-kit config --dir ./docs2 --project-root /new/path
 
 # projectRoot 수정 (Multi)
-npx lee-spec-kit config --project-root /new/fe/path --repo fe
-npx lee-spec-kit config --project-root /new/be/path --repo be
+npx lee-spec-kit config --project-root /new/fe/path --component fe
+npx lee-spec-kit config --project-root /new/be/path --component be
 npx lee-spec-kit config --project-root /new/worker/path --component worker
 
 # 비대화형 모드 (필수 옵션 누락 시 즉시 실패)
-npx lee-spec-kit config --project-root /new/fe/path --repo fe --non-interactive
+npx lee-spec-kit config --project-root /new/fe/path --component fe --non-interactive
 ```
 
 **옵션:**
@@ -609,7 +637,6 @@ npx lee-spec-kit config --project-root /new/fe/path --repo fe --non-interactive
 | -------------------- | ---- |
 | `--dir <dir>` | 대상 docs 디렉터리 또는 프로젝트 경로 지정 |
 | `--project-root <path>` | projectRoot 경로 설정 |
-| `--repo <repo>` | multi 대상 컴포넌트(하위호환 alias) |
 | `--component <id>` | multi 대상 컴포넌트 |
 | `--non-interactive` | 사용자 입력이 필요하면 프롬프트 대신 즉시 실패 |
 
@@ -712,7 +739,7 @@ flowchart LR
 </details>
 
 <details>
-<summary><strong>Multi 프로젝트에서 --repo/--component 옵션이 동작하지 않습니다</strong></summary>
+<summary><strong>Multi 프로젝트에서 --component 옵션이 동작하지 않습니다</strong></summary>
 
 - `.lee-spec-kit.json`의 `projectType`이 `multi`(또는 구버전 `fullstack`)인지 확인하세요
 - `.lee-spec-kit.json`의 `components` 목록에 해당 값이 포함되어 있는지 확인하세요