lee-spec-kit 0.6.7 → 0.6.9

package/README.en.md

@@ -67,7 +67,7 @@ npx lee-spec-kit doctor
 ### 🚀 Feature creation
 
 - Generates `spec.md`, `plan.md`, `tasks.md`, `decisions.md`
-- Multi mode supports flexible component separation (e.g. FE/BE/worker)
+- Multi mode supports flexible component separation (e.g. app/api/worker)
 - Integrates Issue/PR templates (docs side)
 
 ### 📊 Status management
@@ -109,15 +109,14 @@ npx lee-spec-kit init --name my-project --type fullstack  # alias
 | Option              | Description                                                                                 | Default                         |
 | ------------------- | ------------------------------------------------------------------------------------------- | ------------------------------- |
 | `-n, --name <name>` | Project name                                                                                | current folder                  |
-| `-t, --type <type>` | `single` or `multi` (`fullstack` alias supported)                                          | interactive (`single` with `--yes`/`--non-interactive`) |
-| `--components <list>` | multi component list (comma-separated, e.g. `fe,be,worker`)                              | `fe,be`                         |
+| `-t, --type <type>` | `single` or `multi` (`fullstack` alias supported)                                          | interactive (`multi` with `--yes`/`--non-interactive`) |
+| `--components <list>` | multi component list (comma-separated, e.g. `app,api,worker`)                            | `app`                           |
 | `-l, --lang <lang>` | `ko` or `en`                                                                                | `en`                            |
 | `--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                                                   | -                               |
-| `--fe-project-root <path>` | standalone(multi) frontend repo path                                                | -                               |
-| `--be-project-root <path>` | standalone(multi) backend repo path                                                 | -                               |
+| `--project-root <path>` | standalone(single) project repo path or standalone(multi) JSON map (`{"app":"/path/app","api":"/path/api"}`) | -                               |
+| `--component-project-roots <pairs>` | standalone(multi) component roots (`app=/path/app,api=/path/api,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 +125,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 +147,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 api user-auth
+npx lee-spec-kit feature --component app user-profile
 npx lee-spec-kit feature --component worker queue-jobs
 
 # Specify Feature ID/description
@@ -145,7 +159,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 +170,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. `app`, `api`, `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 +264,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. `app`, `api`, `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 +289,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. `app`, `api`, `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 +376,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 +405,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 } },
@@ -392,14 +417,14 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
 | ------------- | ------------------------------------------------ |
 | `projectName` | Project name                                     |
 | `projectType` | `single` or `multi` (`fullstack` alias supported) |
-| `components`  | (multi only) component list (e.g. `["fe","be","worker"]`) |
+| `components`  | (multi only) component list (e.g. `["app","api","worker"]`) |
 | `lang`        | `ko` or `en`                                     |
 | `createdAt`   | Creation date                                    |
 | `docsRepo`    | `embedded` or `standalone`                       |
 | `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 +438,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 +463,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 +481,7 @@ Example:
   "workflow": {
     "mode": "github",
     "codeDirtyScope": "auto",
+    "taskCommitGate": "strict",
     "prePrReview": {
       "skills": ["code-review-excellence"],
       "fallback": "builtin-checklist",
@@ -510,12 +542,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/app/path --component app
+npx lee-spec-kit config --project-root /new/api/path --component api
 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/app/path --component app --non-interactive
 ```
 
 **Options:**
@@ -524,7 +556,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 |