lee-spec-kit 0.9.0 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lee-spec-kit",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Document-centered harness engineering toolkit for AI agent development",
   "type": "module",
   "bin": {
@@ -13,18 +13,6 @@
     "templates",
     "assets"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "lint": "eslint src",
-    "lint:test": "eslint tests",
-    "typecheck": "tsc --noEmit",
-    "typecheck:test": "tsc -p tsconfig.tests.json --noEmit",
-    "test": "pnpm build && vitest run",
-    "test:race": "pnpm build && vitest run tests/race.test.mjs",
-    "format": "prettier --write .",
-    "prepublishOnly": "pnpm build"
-  },
   "keywords": [
     "docs",
     "template",
@@ -66,5 +54,15 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
-  "packageManager": "pnpm@10.7.0"
-}
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "lint:test": "eslint tests",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test": "tsc -p tsconfig.tests.json --noEmit",
+    "test": "pnpm build && vitest run",
+    "test:race": "pnpm build && vitest run tests/race.test.mjs",
+    "format": "prettier --write ."
+  }
+}

package/templates/en/common/README.md

@@ -16,7 +16,7 @@ npx lee-spec-kit docs get agents --json
 - Use workspace-scoped `AGENTS.md`, official Codex hooks, and the active feature docs as the default runtime path.
 - Resolve the active feature, then treat `spec.md`, `plan.md`, `tasks.md`, and `decisions.md` as the working SSOT.
 - Ask for approval only at documented workflow checkpoints and before remote or destructive actions.
-- Use `npx lee-spec-kit commit-audit --json` before `git commit` when staged docs paths need validation.
+- Use `npx lee-spec-kit commit-audit --json` before `git commit` for staged docs-path checks and canonical Feature-scoped commit validation.
 - Use `npx lee-spec-kit workflow-audit --json` before stopping when code or feature docs changed.
 - If `isLeeSpecKitProject: false`, skip lee-spec-kit-specific flow and continue with normal workflow.
 
@@ -136,18 +136,19 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   - `reasoningEffort`: `low | medium | high | xhigh | max | ultra`
   - `onUnavailable`: `inherit | error` when the requested model is unavailable
 - `workflow.baseBranch` (string): branch that receives a completed local Feature
-- `workflow.completionStrategy` (`"local-ff" | "none"`): fast-forward and verify local Features before `done`, or explicitly finish without integration
+- `workflow.completionStrategy` (`"local-ff" | "local-squash" | "none"`): fast-forward, create one verified squash commit, or explicitly finish without integration
 - `workflow.deleteFeatureBranchAfterMerge` (boolean): delete the integrated local Feature branch after cleanup; remote branches are never deleted
-- `workflow.postMergeChecks` (array): structured commands run from the base branch after local integration, for example `{ "command": "pnpm", "args": ["test"] }`
+- `workflow.featureChecks` (array): build/test/lint/typecheck commands run in the Feature worktree before integration
+- `workflow.postMergeChecks` (array): optional commands that genuinely require the integrated base-branch environment
 - `approval` (object, optional): optional approval-checkpoint metadata for repo policy and custom validators
   - The Codex-native default path still asks at documented checkpoints and before remote/destructive actions first.
   - Legacy runtime consumed this field directly; keep it only when you intentionally want category-based checkpoint metadata.
   - Current default:
     - `mode: "category"`
     - `default: "skip"`
-    - `requireCheckCategories: ["spec_approve", "implementation_approve"]`
-  - In a `local-ff` workflow, `implementation_approve` explicitly authorizes the remaining fast-forward integration, post-merge checks, managed-worktree removal, and configured local Feature-branch deletion.
-  - Add `local_merge` to `requireCheckCategories` when a separate approval immediately before integration is required.
+    - `requireCheckCategories: ["spec_approve", "implementation_approve", "local_merge"]`
+  - In a `local-ff` or `local-squash` workflow, `implementation_approve` approves the completed implementation and `local_merge` separately authorizes the configured integration, post-merge checks, managed-worktree removal, and configured local Feature-branch deletion.
+  - Remove `local_merge` from `requireCheckCategories` only when the implementation approval should authorize the remaining local completion flow without another checkpoint.
   - Approval token: `A`
   - Accepted replies: `A`, `A OK`
 - `allowedDocsEntries` (object, optional): Allowlist non-standard top-level docs entries so they are not treated as unmanaged docs
@@ -168,6 +169,7 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
     "baseBranch": "main",
     "completionStrategy": "local-ff",
     "deleteFeatureBranchAfterMerge": true,
+    "featureChecks": [],
     "postMergeChecks": [],
     "prePrReview": {
       "evidenceMode": "path_required",
@@ -185,12 +187,12 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve"]
+    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
   }
 }
 ```
 
-New local projects use `local-ff`. During `update`, an existing local project with no explicit `completionStrategy` receives `none` so an upgrade does not unexpectedly merge its current branch. Set it to `local-ff` deliberately when ready.
+New local projects use `local-ff`. Choose `local-squash` to create one base-branch commit while preserving the source Feature tip under an internal `refs/lee-spec-kit/integrations/*` ref for task-checkpoint evidence. During `update`, an existing local project with no explicit `completionStrategy` receives `none` so an upgrade does not unexpectedly merge its current branch. Set it to `local-ff` or `local-squash` deliberately when ready.
 
 ```json
 {
@@ -204,7 +206,7 @@ New local projects use `local-ff`. During `update`, an existing local project wi
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve"]
+    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
   }
 }
 ```

package/templates/en/common/agents/agents.md

@@ -42,6 +42,12 @@ This document defines workflow policy, not a custom runtime loop.
 - Do not use `docs/designs/` for system architecture, data/API design, technical research, or implementation plans.
 - Follow the detailed routing rules in `docs/README.md`.
 
+## Optional UI/UX Design Policy
+
+- Only when the user request explicitly mentions a design system, UI/visual redesign, design consistency, shared UI/component-library consolidation, branding/theme/token redesign, or implementation from Figma/design images, read and apply `npx lee-spec-kit docs get ui-ux-design --json`.
+- Do not apply this policy merely because the target is web/frontend, to a non-UI/backend Feature, or to a simple bug fix unrelated to durable design rules.
+- This is optional guidance, not a `requiredDocs` entry or workflow approval gate.
+
 ## Execution Rules
 
 - lee-spec-kit owns docs structure, workflow stages, and validators.
@@ -51,10 +57,10 @@ This document defines workflow policy, not a custom runtime loop.
 - The Pre-PR review subagent returns findings without modifying code. The main agent remediates findings and records reviewer metadata and the final decision as evidence.
 - Treat spec/plan/tasks approval, issue creation, and branch creation as hard gates before implementation.
 - In standalone mode, do not hand-write `git worktree add`; run the exact `nextAction.command` from `workflow-stage` so the managed workspace path, stale directory cleanup, and `.env`/`.env.*` copy step stay consistent.
-- In local mode, do not stop after implementation approval. Follow the exact `local merge` and `local cleanup` commands returned by `workflow-stage` until verified integration and cleanup produce `done`.
-- In a `local-ff` workflow, present the returned implementation-approval summary without weakening it: that checkpoint authorizes fast-forward integration, post-merge checks, and configured local cleanup. Ask again at `local_merge` only when that category is explicitly required.
+- In local mode, do not stop after implementation approval. Follow the exact `local verify`, `local merge`, and `local cleanup` commands returned by `workflow-stage` until verified integration and cleanup produce `done`. A `feature_remediation` stage explicitly permits fixes in the Feature worktree.
+- In a `local-ff` or `local-squash` workflow, keep implementation approval and local merge approval distinct when `local_merge` is required: the first accepts the implementation, and the second authorizes the configured integration strategy, post-merge checks, and local cleanup.
 - Keep docs synced with code changes in the same turn whenever behavior or scope changes.
-- Use `npx lee-spec-kit commit-audit --json` before `git commit` when staged docs paths need validation.
+- Use `npx lee-spec-kit commit-audit --json` before `git commit`; Feature-scoped commits use `#123` when an Issue is linked and the stable Feature ID such as `F027` for issue-less local workflows.
 - Use `npx lee-spec-kit workflow-audit --json` as the default end-of-turn docs sync check.
 
 ## Approval Rules

package/templates/en/common/agents/git-workflow.md

@@ -6,11 +6,11 @@ Rules for AI agents to automate Git/GitHub operations.
 
 ## Core Concepts
 
-| Concept          | GitHub Mapping | Description                     |
-| ---------------- | -------------- | ------------------------------- |
-| Feature          | GitHub Issue   | Feature-level work unit         |
-| Task             | Commit         | Individual implementation unit  |
-| Feature Complete | Pull Request   | Create PR on feature completion |
+| Concept          | GitHub Workflow | Local Workflow | Description                     |
+| ---------------- | --------------- | -------------- | ------------------------------- |
+| Feature          | GitHub Issue    | Feature ID     | Feature-level work unit         |
+| Task             | Commit          | Commit         | Individual implementation unit  |
+| Feature Complete | Pull Request    | Local merge    | Feature completion integration  |
 
 ---
 
@@ -50,10 +50,27 @@ main
 
 ### Format
 
-```
+Use exactly one canonical Feature scope. Do not invent alternate scope forms.
+
+```text
+# Feature linked to a GitHub Issue
 {type}(#{issue}): {description}
+
+# Issue-less local Feature
+{type}({featureId}): {description}
+```
+
+Examples:
+
+```text
+feat(#123): implement user auth
+docs(#123): clarify auth spec
+feat(F027): implement notification settings
+docs(F027): update notification docs
 ```
 
+For local Features, the scope is the stable Feature ID (`F027`), not the full folder ref (`F027-notification-settings`). Feature-scoped commits without a scope, such as `docs: F027 ...`, are not canonical.
+
 ### Type List
 
 | Type       | Description   | Example                               |
@@ -115,15 +132,17 @@ git worktree add .worktrees/feat-{issue-number}-{feature-name} feat/{issue-numbe
 
 #### Standalone Mode Commit Guide
 
+Use the scope selected by the workflow: `#123` when an Issue is linked, otherwise the local Feature ID such as `F027`.
+
 1. **Project Commit** (If code changed)
 
    ```bash
-   git commit -m "feat(#123): implement feature"
+   git commit -m "feat(F027): implement feature"
    ```
 
 2. **Docs Commit** (If docs changed - **Run in Docs Repo**)
    ```bash
-   git commit -m "docs(#123): update feature docs"
+   git commit -m "docs(F027): update feature docs"
    ```
 
 > 💡 **Core Rule**: At task completion, **all changed repositories** must be committed.

package/templates/en/common/agents/skills/split-feature.md

@@ -16,7 +16,8 @@ Use this guide when one Feature/Issue becomes too large to review safely.
 Notes:
 
 - Keep one issue only for small, tightly coupled work.
-- Preserve "Feature = Issue" by creating multiple linked child issues/features.
+- In GitHub workflow, create one linked child Issue for each child Feature.
+- In local workflow, track each child Feature by its own Feature ID without requiring Issues.
 
 ---
 

package/templates/en/common/agents/ui-ux-design.md

@@ -0,0 +1,128 @@
+# UI/UX Design Documentation Policy
+
+This optional policy separates durable design rules from Feature-specific visual material in UI/UX work.
+It does not add a workflow stage or approval gate.
+
+---
+
+## Activation Conditions
+
+Apply this policy **only when the user request explicitly includes** one of these intents:
+
+- a design system
+- a UI redesign or visual redesign
+- design consistency
+- shared UI or component-library consolidation
+- branding or theme/token redesign
+- implementation from Figma or design images
+
+Do not apply it merely because:
+
+- the target component is web/frontend
+- the Feature is backend or otherwise non-UI
+- the request is a simple bug fix that does not change durable design rules
+- the change is a local style adjustment to one existing component
+
+If the signal is ambiguous, do not create design docs; use only the active Feature docs.
+
+## Recommended Structure
+
+When an activation condition is met and durable rules or visual references are actually needed, use only the necessary parts of this structure:
+
+```text
+docs/designs/
+├── README.md
+├── design-system.md
+├── <feature-visual-brief>.md
+└── assets/
+    └── <feature-name>/
+```
+
+- Do not create every file preemptively.
+- If `docs/designs/design-system.md` already exists, reference or update it instead of creating a replacement.
+- Do not make one `design.md` per Feature the default.
+- Do not migrate an existing project's document structure or make these documents a required gate.
+
+## Document Responsibilities
+
+### `docs/designs/design-system.md`
+
+Record durable meaning and usage rules shared by multiple Features:
+
+- semantic color tokens
+- typography
+- spacing and layout
+- radius, border, and shadow
+- shared components and variants
+- states such as loading, empty, error, and processing
+- responsive rules
+- accessibility and motion rules
+- content voice
+- design-system change, deprecation, and synchronization policy
+
+Use this frontmatter:
+
+```yaml
+---
+lee-spec-kit:
+  kind: design-system
+  scope: project
+---
+```
+
+### `docs/designs/<feature-visual-brief>.md`
+
+Record the UX direction and visual references for one Feature:
+
+- original Figma URLs and any necessary repository snapshots
+- design images and reference screens
+- intent and key states for each screen or flow
+- gaps between the current data/API contract and the design
+- applicable `design-system.md` rules and Feature-specific interpretation
+
+Use `kind: ux-design` or `kind: visual-reference` with `scope: project`, as appropriate. This document is the Feature's visual reference authority; it does not replace the authorities for requirements, implementation planning, or technical decisions.
+
+### Feature `spec.md`
+
+- Keep user requirements and acceptance criteria here.
+- Link the design system and visual brief through optional `Design Refs` using project-root paths.
+
+### Feature `plan.md`
+
+- Record the change surface for token/theme files, shared components, routes/screens, and Storybook or an equivalent workbench.
+- Explain how design rules map to executable code and tests.
+
+### Feature `decisions.md`
+
+- Record why the design system changed or why an exception exists.
+- Include the exception scope, affected rule, and removal condition.
+
+## Executable Authorities and Responsibility Split
+
+Do not treat `design-system.md` as the only source of truth.
+
+| Surface                           | Responsibility                                       |
+| --------------------------------- | ---------------------------------------------------- |
+| `docs/designs/design-system.md`   | Meaning, intent, and usage rules                     |
+| CSS theme/globals or token files  | Executed token values                                |
+| Shared UI directory               | Executed component APIs and variant contracts        |
+| Storybook or equivalent workbench | Executable examples of variants and states           |
+| Feature `decisions.md`            | Exceptions, change rationale, and removal conditions |
+
+The document explains meaning; code and the workbench prove the executable contract.
+
+## Synchronization Rules
+
+- When a Feature changes `design-system.md`, use the same `tasks.md` task to name the affected design docs, token/theme files, shared UI, Storybook/workbench examples, and relevant verification.
+- Do not force edits to an unaffected surface, but confirm its impact explicitly in the task checklist.
+- If docs and code diverge, synchronize the affected documents and executable authorities in the same Feature task.
+- Record design-system exceptions and their removal conditions in `decisions.md`.
+- Store visual-reference files under a repository path such as `docs/designs/assets/<feature-name>/`; never depend on an absolute path from one person's computer.
+- Keep the external Figma or source URL for provenance, and also reference a repository asset when implementation depends on a fixed snapshot.
+
+## Backward Compatibility
+
+- `design-system.md`, visual briefs, and `Design Refs` are all optional.
+- Existing Feature docs do not need the new section backfilled.
+- This policy does not change spec/plan/tasks approvals or `workflow-stage` results.
+- For requests that do not match an explicit UI/UX activation condition, use the existing Feature-doc workflow only.

package/templates/en/common/designs/README.md

@@ -6,12 +6,39 @@ Store design references used by the project.
 
 ---
 
+## Optional Use
+
+`design-system.md` and Feature visual briefs are not required documents for every project.
+
+- Consider them only for an explicit design-system, UI/visual-redesign, design-consistency, shared-UI/component-library, branding/theme/token, or Figma/design-image implementation request.
+- Do not create them for an ordinary web/frontend Feature, a backend Feature, or a bug fix that does not change durable design rules.
+- Detailed policy: `npx lee-spec-kit docs get ui-ux-design --json`
+
+---
+
 ## What belongs here
 
 - Screen/flow references (Figma, images, links)
 - Component/pattern guidelines (buttons, forms, navigation, etc.)
 - UI rules (brand, typography, colors/tokens)
 
+## Recommended Structure and Responsibilities
+
+```text
+docs/designs/
+├── README.md
+├── design-system.md
+├── <feature-visual-brief>.md
+└── assets/
+    └── <feature-name>/
+```
+
+- `design-system.md`: meaning and usage rules shared across Features
+- `<feature-visual-brief>.md`: Feature-specific Figma/images, UX direction, and gaps between the data contract and design
+- `assets/<feature-name>/`: repository-owned visual snapshots required by implementation
+
+If `design-system.md` already exists, reference or update it instead of creating a replacement. Do not make one `design.md` per Feature the default.
+
 ---
 
 ## What does not belong here
@@ -30,7 +57,18 @@ In `designs/`, design means UX, screen, and visual design—not technical design
 
 - For external references, keep the **source URL + a short summary (or a snapshot)**.
 - Use kebab-case filenames (e.g., `auth-flow.md`, `design-system.md`).
-- If you need images/files, create and use an `assets/` folder.
+- Keep images/files in a repository path such as `assets/<feature-name>/`; never depend on an absolute path from one person's computer.
+- Use `scope: project` and the appropriate `kind: ux-design`, `kind: design-system`, or `kind: visual-reference` frontmatter.
+
+## Executable Authorities
+
+- `design-system.md`: meaning and usage rules
+- CSS theme/globals or token files: executed token values
+- Shared UI directory: executed component and variant contracts
+- Storybook or equivalent workbench: executable variant and state examples
+- Feature `decisions.md`: exceptions, change rationale, and removal conditions
+
+When `design-system.md` changes, use the same Feature task to review and synchronize affected docs, token/theme files, shared UI, Storybook/workbench examples, and verification.
 
 ---
 

package/templates/en/common/features/README.md

@@ -45,7 +45,7 @@ By the time work reaches this folder, the requirement should already be defined
 - Minimum **3-digit padding** for numbers (001, 002, ...)
 - Expands to **4+ digits** beyond 999 (F1000, F1001, ...)
 - Feature names in kebab-case
-- **Feature = Issue**: Each Feature corresponds to one GitHub Issue.
+- **Feature identity is workflow-dependent**: In GitHub workflow, each Feature corresponds to one GitHub Issue. In local workflow, the canonical identity is the stable Feature ID such as `F027`; no Issue is required.
 
 ---
 
@@ -57,7 +57,11 @@ npx lee-spec-kit workflow-stage <feature-ref> --json
 
 Use the returned `stage`, `nextAction`, and `implementationAllowed` values as the current workflow state.
 
-In a local workflow with `completionStrategy: "local-ff"`, completion is `implementation_approve → local_merge → local_verify → local_cleanup → done`. Use the exact helper command returned for each stage; `done` means the base branch contains the Feature tip and cleanup is complete.
+The three final completion checkboxes in `tasks.md` carry `lee-spec-kit:completion:*` HTML markers. You may customize their visible wording, but preserve the marker on each checkbox line; `workflow-stage` uses the marker as the machine-readable identity and falls back to the legacy canonical wording for older projects.
+
+In a local workflow with `completionStrategy: "local-ff"` or `"local-squash"`, completion is `implementation_approve → feature_verify → local_merge → local_cleanup → done`. Failed checks enter `feature_remediation` with implementation enabled. `local-ff` moves only the verified Feature SHA; `local-squash` requires the integration tree to match the verified Feature tree. Both require cleanup before `done`.
+
+A remediation commit invalidates verification and the prior local-merge confirmation. Refresh review evidence for the changed diff when Pre-PR review is enabled, verify the new tip, and obtain local-merge approval again.
 
 ---
 

package/templates/en/common/features/feature-base/decisions.md

@@ -6,7 +6,8 @@ If unmanaged docs artifacts exist outside the canonical docs surface (for exampl
 > ADR (Architecture Decision Record) captures important technical or architectural choices made during implementation.
 > Write ADRs so the team can trace why a choice was made and revisit trade-offs later.
 
-> Format: `D{number}: {Decision Title} ({YYYY-MM-DD})`
+> Format: `DNNN: {Decision Title} ({YYYY-MM-DD})`
+> Decision IDs are scoped to this Feature and start at `D001`, independently of the Feature ID.
 
 Recording principles:
 
@@ -17,6 +18,7 @@ Recording principles:
   - Right before task done (`[DOING] -> [DONE]`): finalize `Options/Decision/Rationale` and enrich `Trace`
   - After PR merge: append 1-2 lines in `Trace (post-merge check)` with actual outcome/impact
 - Every ADR must include at least one **Evidence link** (commit, PR, or test/log evidence).
+- For a design-system change or exception, also record the affected rule and scope, rationale, removal condition, and synchronization impact on executable authorities.
 
 ---
 

package/templates/en/common/features/feature-base/spec.md

@@ -60,3 +60,6 @@
   - If this is a legacy requirements doc without PRD IDs yet, backfill IDs in the source first, then update this field and the `tasks.md` task tags together.
   - When requirements/scope change, update PRD docs + this field + `tasks.md` task tags together.
   - If implementation discovers a better user-facing behavior and the shipped requirement changes, treat that as a PRD update, not a permanent `[NON-PRD]` exception.
+- Design Refs: - (optional; use project-root paths only for explicit UI/UX design work)
+  - Design System: - (e.g. `docs/designs/design-system.md`)
+  - Visual Brief: - (e.g. `docs/designs/<feature-visual-brief>.md`)

package/templates/en/common/features/feature-base/tasks.md

@@ -13,6 +13,7 @@
   - Do not invent PRD IDs in `tasks.md`. Only reference IDs that already exist in `docs/prd` or the upstream requirements doc.
   - If this is a legacy feature without PRD IDs yet, backfill IDs in the source requirements doc first, then align `spec.md` `PRD Refs` and task tags together.
   - `[NON-PRD]` is for internal implementation work only. If the task changes user-facing behavior, acceptance criteria, or scope, backfill PRD first and tag it as `[PRD-...]`.
+- **Design-system synchronization (conditional)**: when a task changes `docs/designs/design-system.md`, track the affected design docs, token/theme files, shared UI, Storybook/workbench examples, and verification in that same task's `Checklist`. Do not edit an unaffected surface; confirm its impact instead.
 
 ---
 
@@ -80,9 +81,9 @@
 
 > ⚠️ This is a **final verification checklist**. Only check after you actually verified.
 
-- [ ] All tasks are `[DONE]`, and each task's `Acceptance` is verified and `Checklist` is checked
-- [ ] Tests executed and passing (record command/result below)
-- [ ] Final outcome shared and any required user confirmation recorded at the documented workflow checkpoint
+- [ ] All tasks are `[DONE]`, and each task's `Acceptance` is verified and `Checklist` is checked <!-- lee-spec-kit:completion:all-tasks -->
+- [ ] Tests executed and passing (record command/result below) <!-- lee-spec-kit:completion:tests -->
+- [ ] Final outcome shared and any required user confirmation recorded at the documented workflow checkpoint <!-- lee-spec-kit:completion:final-outcome -->
 
 ### Test Run Log (Latest by Command)
 

package/templates/ko/common/README.md

@@ -16,7 +16,7 @@ npx lee-spec-kit docs get agents --json
 - 기본 실행 경로는 workspace-scoped `AGENTS.md`, Codex 공식 hooks, 그리고 활성 feature 문서입니다.
 - 활성 feature를 정한 뒤에는 `spec.md`, `plan.md`, `tasks.md`, `decisions.md`를 작업 SSOT로 사용합니다.
 - 사용자 승인 요청은 문서화된 workflow checkpoint와 원격/파괴적 작업 전에만 합니다.
-- staged된 docs 경로 검사가 필요하면 `git commit` 전에 `npx lee-spec-kit commit-audit --json`를 사용합니다.
+- `git commit` 전에 `npx lee-spec-kit commit-audit --json`를 사용해 staged docs 경로와 canonical Feature-scoped commit 형식을 검증합니다.
 - 코드나 feature 문서를 바꿨다면 종료 전 `npx lee-spec-kit workflow-audit --json`로 동기화 상태를 확인합니다.
 - `isLeeSpecKitProject: false`면 lee-spec-kit 전용 절차를 건너뛰고 일반 워크플로우로 진행합니다.
 
@@ -136,18 +136,19 @@ npx lee-spec-kit docs get agents --json
   - `reasoningEffort`: `low | medium | high | xhigh | max | ultra`
   - `onUnavailable`: 지정 모델을 사용할 수 없을 때 `inherit | error`
 - `workflow.baseBranch` (string): 완료된 local Feature를 통합할 기준 브랜치
-- `workflow.completionStrategy` (`"local-ff" | "none"`): `done` 전에 local Feature를 fast-forward 병합·검증하거나, 명시적으로 통합 없이 종료
+- `workflow.completionStrategy` (`"local-ff" | "local-squash" | "none"`): fast-forward, 검증된 단일 squash commit 생성, 또는 명시적으로 통합 없이 종료
 - `workflow.deleteFeatureBranchAfterMerge` (boolean): cleanup 후 통합된 local Feature 브랜치 삭제 여부. 원격 브랜치는 삭제하지 않음
-- `workflow.postMergeChecks` (array): local 통합 뒤 기준 브랜치에서 실행할 구조화 명령. 예: `{ "command": "pnpm", "args": ["test"] }`
+- `workflow.featureChecks` (array): 통합 전에 Feature worktree에서 실행할 build/test/lint/typecheck 명령
+- `workflow.postMergeChecks` (array): 통합된 기준 브랜치 환경이 실제로 필요한 선택적 검사
 - `approval` (object, optional): repo 정책/커스텀 validator용 승인 checkpoint 메타데이터
   - 기본 Codex-native 경로는 여전히 문서화된 checkpoint와 원격/파괴적 작업을 우선 기준으로 승인 요청합니다.
   - legacy runtime은 이 필드를 직접 소비했지만, 이제는 category 기반 checkpoint 메타데이터가 정말 필요할 때만 유지하세요.
   - 현재 기본값:
     - `mode: "category"`
     - `default: "skip"`
-    - `requireCheckCategories: ["spec_approve", "implementation_approve"]`
-  - `local-ff` workflow에서 `implementation_approve`는 이후의 fast-forward 통합, post-merge 검사, managed worktree 제거, 설정된 local Feature 브랜치 삭제까지 명시적으로 승인합니다.
-  - 통합 직전 별도 승인이 필요하면 `requireCheckCategories`에 `local_merge`를 추가하세요.
+    - `requireCheckCategories: ["spec_approve", "implementation_approve", "local_merge"]`
+  - `local-ff` 또는 `local-squash` workflow에서 `implementation_approve`는 완료된 구현을 승인하고, `local_merge`는 설정된 통합, post-merge 검사, managed worktree 제거, 설정된 local Feature 브랜치 삭제를 별도로 승인합니다.
+  - 구현 승인 한 번으로 남은 local 완료 흐름까지 진행하려는 경우에만 `requireCheckCategories`에서 `local_merge`를 제거하세요.
   - 승인 토큰: `A`
   - 허용 응답: `A`, `A OK`
 - `allowedDocsEntries` (object, optional): 비표준 `docs/` top-level 엔트리를 unmanaged docs로 보지 않도록 허용 목록에 추가
@@ -168,6 +169,7 @@ npx lee-spec-kit docs get agents --json
     "baseBranch": "main",
     "completionStrategy": "local-ff",
     "deleteFeatureBranchAfterMerge": true,
+    "featureChecks": [],
     "postMergeChecks": [],
     "prePrReview": {
       "evidenceMode": "path_required",
@@ -185,12 +187,12 @@ npx lee-spec-kit docs get agents --json
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve"]
+    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
   }
 }
 ```
 
-새 local 프로젝트는 `local-ff`를 사용합니다. 기존 local 프로젝트에 명시적 `completionStrategy`가 없으면 `update`가 `none`을 넣어 업그레이드 도중 현재 브랜치를 갑자기 병합하지 않습니다. 준비가 끝난 뒤 `local-ff`로 명시적으로 전환하세요.
+새 local 프로젝트는 `local-ff`를 사용합니다. base branch에 하나의 commit만 남기려면 `local-squash`를 선택하세요. 이때 task checkpoint 증거를 위해 원본 Feature tip을 내부 `refs/lee-spec-kit/integrations/*` ref로 보존합니다. 기존 local 프로젝트에 명시적 `completionStrategy`가 없으면 `update`가 `none`을 넣어 업그레이드 도중 현재 브랜치를 갑자기 병합하지 않습니다. 준비가 끝난 뒤 `local-ff` 또는 `local-squash`로 명시적으로 전환하세요.
 
 ```json
 {
@@ -204,7 +206,7 @@ npx lee-spec-kit docs get agents --json
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve"]
+    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
   }
 }
 ```

package/templates/ko/common/agents/agents.md

@@ -42,6 +42,12 @@
 - `docs/designs/`를 시스템 아키텍처, 데이터/API 설계, 기술 조사, 구현 계획의 목적지로 사용하지 않습니다.
 - 세부 설명은 `docs/README.md`의 문서 라우팅 규칙을 따릅니다.
 
+## 선택적 UI/UX 디자인 정책
+
+- 사용자 요청에 design system, UI/visual redesign, 디자인 일관성, 공통 UI/component library 정리, branding/theme/token 재설계, Figma/디자인 이미지 기반 구현이 명시된 경우에만 `npx lee-spec-kit docs get ui-ux-design --json`을 읽고 적용합니다.
+- 단순히 대상이 web/frontend인 경우, 비 UI/backend Feature, 장기 디자인 규칙과 무관한 단순 버그 수정에는 이 정책을 적용하지 않습니다.
+- 이 문서는 선택적 권장 정책이며 `requiredDocs`나 workflow 승인 gate가 아닙니다.
+
 ## 실행 규칙
 
 - lee-spec-kit은 문서 구조, workflow 단계, validator를 담당합니다.
@@ -51,10 +57,10 @@
 - Pre-PR 리뷰 서브에이전트는 finding만 반환하며 코드를 수정하지 않습니다. 메인 에이전트가 finding을 반영하고 reviewer metadata와 최종 decision을 evidence에 기록합니다.
 - spec / plan / tasks 승인, issue 생성, branch 생성은 구현 전 하드 게이트로 취급합니다.
 - standalone 모드에서는 `git worktree add`를 직접 만들지 말고 `workflow-stage`의 정확한 `nextAction.command`를 실행해 managed workspace 경로, stale 디렉터리 정리, `.env`/`.env.*` 복사 단계가 일관되게 유지되도록 합니다.
-- local 모드에서는 구현 승인 직후 종료하지 않습니다. `workflow-stage`가 반환하는 정확한 `local merge`, `local cleanup` 명령을 따라 통합·검증·정리가 확인되어 `done`이 될 때까지 진행합니다.
-- `local-ff` workflow에서는 반환된 구현 승인 설명을 축소하지 않고 그대로 제시합니다. 이 checkpoint는 fast-forward 통합, post-merge 검사, 설정된 local cleanup까지 승인하며, `local_merge` category가 명시적으로 승인 대상으로 설정된 경우에만 통합 직전 다시 요청합니다.
+- local 모드에서는 구현 승인 직후 종료하지 않습니다. `workflow-stage`가 반환하는 정확한 `local verify`, `local merge`, `local cleanup` 명령을 따라 검증·통합·정리가 확인되어 `done`이 될 때까지 진행합니다. `feature_remediation` 단계에서는 Feature worktree 수정이 명시적으로 허용됩니다.
+- `local-ff` 또는 `local-squash` workflow에서 `local_merge` 승인이 필요하면 구현 승인과 local merge 승인을 구분합니다. 첫 번째 승인은 구현 결과를 수락하고, 두 번째 승인은 설정된 통합 전략, post-merge 검사, local cleanup을 허가합니다.
 - 동작이나 범위가 바뀌는 코드 변경이 있으면 같은 턴 안에서 feature 문서를 같이 동기화합니다.
-- staged된 docs 경로 검사가 필요하면 `git commit` 전에 `npx lee-spec-kit commit-audit --json`를 사용합니다.
+- `git commit` 전에 `npx lee-spec-kit commit-audit --json`를 사용합니다. Feature-scoped commit은 Issue가 연결되어 있으면 `#123`, Issue 없는 local workflow에서는 `F027` 같은 안정적인 Feature ID를 scope로 사용합니다.
 - 기본 docs sync 검사는 `npx lee-spec-kit workflow-audit --json`를 사용합니다.
 
 ## 승인 규칙

package/templates/ko/common/agents/git-workflow.md

@@ -6,11 +6,11 @@
 
 ## 핵심 개념
 
-| 개념      | GitHub 매핑  | 설명                    |
-| --------- | ------------ | ----------------------- |
-| Feature   | GitHub Issue | 기능 단위 작업          |
-| 태스크    | Commit       | 개별 구현 단위          |
-| 기능 완료 | Pull Request | Feature 완료 시 PR 생성 |
+| 개념      | GitHub workflow | Local workflow | 설명                    |
+| --------- | --------------- | -------------- | ----------------------- |
+| Feature   | GitHub Issue    | Feature ID     | 기능 단위 작업          |
+| 태스크    | Commit          | Commit         | 개별 구현 단위          |
+| 기능 완료 | Pull Request    | Local merge    | Feature 완료 통합       |
 
 ---
 
@@ -50,10 +50,27 @@ main
 
 ### 형식
 
-```
+Feature scope는 아래 canonical 형식 중 하나만 사용하며, 에이전트가 임의의 scope 형식을 만들지 않습니다.
+
+```text
+# GitHub Issue가 연결된 Feature
 {type}(#{issue}): {description}
+
+# Issue가 없는 local Feature
+{type}({featureId}): {description}
+```
+
+예:
+
+```text
+feat(#123): 사용자 인증 구현
+docs(#123): 인증 스펙 명확화
+feat(F027): 알림 설정 구현
+docs(F027): 알림 문서 업데이트
 ```
 
+local Feature의 scope는 안정적인 Feature ID(`F027`)입니다. 전체 폴더 ref인 `F027-notification-settings`를 scope로 사용하지 않으며, `docs: F027 ...`처럼 Feature scope를 생략한 커밋도 canonical 형식이 아닙니다.
+
 ### Type 목록
 
 | Type       | 설명        | 예시                                |
@@ -114,15 +131,17 @@ git worktree add .worktrees/feat-{issue-number}-{feature-name} feat/{issue-numbe
 
 #### Standalone 모드 커밋 가이드
 
+workflow에 따라 scope를 선택합니다. Issue가 연결되어 있으면 `#123`, Issue 없는 local Feature라면 `F027` 같은 Feature ID를 사용합니다.
+
 1. **Project 커밋** (코드 변경사항이 있는 경우)
 
    ```bash
-   git commit -m "feat(#123): 기능 구현"
+   git commit -m "feat(F027): 기능 구현"
    ```
 
 2. **Docs 커밋** (문서 변경사항이 있는 경우 - **Docs 레포에서 실행**)
    ```bash
-   git commit -m "docs(#123): 기능 구현 문서 업데이트"
+   git commit -m "docs(F027): 기능 구현 문서 업데이트"
    ```
 
 > 💡 **Core Rule**: 태스크 완료 시점에는 **변경된 모든 레포지토리**가 커밋되어야 합니다.