@loviusc/sa-spec 0.2.1 → 0.2.2

package/README.en.md

@@ -0,0 +1,155 @@
+# sa-spec - System Analysis AI Workspace
+
+[![npm version](https://img.shields.io/npm/v/@loviusc/sa-spec.svg)](https://www.npmjs.com/package/@loviusc/sa-spec)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> A lightweight, defensive system analysis documentation workspace that turns ideas into verifiable, auditable, and conflict-checked engineering specifications for AI-driven development.
+
+<p align="center">
+  <b>🌐 Languages:</b>
+  <a href="./README.en.md"><b>English</b></a> |
+  <a href="./README.zh-TW.md"><b>繁體中文</b></a> |
+  <a href="./README.zh-CN.md"><b>简体中文</b></a> |
+  <a href="./README.ja.md"><b>日本語</b></a> |
+  <a href="./README.ko.md"><b>한국어</b></a>
+</p>
+
+---
+
+## Overview
+
+`sa-spec` is not just a document generator; it is a **pre-development system analysis workspace**.
+
+Before code-generation AI tools (OpenSpec, Claude Code, OpenAI Codex, Gemini CLI, Cursor) start implementation, `sa-spec` clarifies scopes, boundaries, data schemas, API contracts, permission matrices, and acceptance criteria to ensure that subsequent coding proceeds within safe, well-defined boundaries.
+
+The AI workflow operates on four standard commands (with shorthand aliases):
+
+| Command | Alias | Purpose | Description |
+|---|---|---|---|
+| `spec:init` | `sci` | Initialize | Sets up `AGENTS.md`, system rules, and prompts for the target language. |
+| `spec:propose` | `scp` | Propose | Summarizes objectives, user stories, workflows, and open items without altering existing requirements. |
+| `spec:analyze` | `sca` | Analyze & Draft | Checks for conflicts against existing requirements, APIs, and DB schemas; drafts SRS, UML, OpenAPI, and DB schema. |
+| `spec:commit` | `scc` | Commit & Archive | Archives the user-verified version, assigns sequential ID, updates indexes, and generates a local Git commit. |
+
+Each finalized requirement produces a standardized, self-contained directory:
+
+```text
+project/
+  REQ-001-login/
+    srs.md           # Software Requirements Specification
+    uml/
+      main.puml      # Standalone PlantUML diagrams (single-diagram-per-file)
+    openapi.yaml     # OpenAPI 3.0 specification draft
+    db-schema.md     # Database schema and migration draft
+    handoff.md       # AI developer handoff brief (OpenSpec / Claude Code entry point)
+    history.md       # Version history and decision audit trail
+```
+
+---
+
+## Design Philosophy
+
+```text
+sa-spec defines what to build and its constraints; AI code tools build it right.
+```
+
+1. **Defensive Impact Assessment**: `spec:analyze` enforces conflict detection. It explicitly checks whether a new requirement mutates existing roles, permissions, API signatures, or database tables, preventing regressions and security flaws.
+2. **Deterministic State Machine**: `propose -> analyze -> commit`. The AI is strictly prohibited from inventing unconfirmed business assumptions or hallucinating table columns. If conflicts are detected, document generation halts until the user clarifies.
+3. **AI Developer Handoff (`handoff.md`)**: Acts as a concise, unambiguous constraint summary for development tools like OpenSpec, Claude Code, or Codex, detailing what to implement, what NOT to touch, and exact acceptance criteria.
+
+---
+
+## Installation
+
+### Prerequisites
+- Node.js 18 or above
+- npm
+- Git
+
+### Global Installation via npm
+
+```bash
+npm install -g @loviusc/sa-spec
+```
+
+Verify installation:
+
+```bash
+sa-spec help
+sa-spec --version
+```
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `sa-spec init [--full] [--lang <lang>]` | Scaffolds the workspace skeleton (Supports `zh-TW`, `en`, `zh-CN`, `ja`, `ko`). |
+| `sa-spec new [--id REQ-001] --name login [--branch]` | Creates a requirement folder template. Omitting `--id` starts a draft in a feature branch (`feat/<name>`). |
+| `sa-spec finalize --name login` | Assigns the latest available sequential ID to a draft requirement, renames directory, substitutes `{{REQ_ID}}`, and regenerates index. |
+| `sa-spec reindex` | Scans `project/REQ-*` directories and dynamically rebuilds `project/index.md` sorted by numerical ID. |
+| `sa-spec check` | Validates required project files and system spec status. |
+| `sa-spec status` | Displays overview status of requirements and specs. |
+| `sa-spec doctor` | Diagnostic tool to verify workspace integrity. |
+| `sa-spec upgrade [--dry-run]` | Upgrades project rules, templates, and agent configs to the latest version while preserving existing language. |
+
+---
+
+## Multi-User Collaboration & Git-Flow
+
+To solve sequential ID collisions and Git merge conflicts in team environments, `sa-spec` introduces **Feature Branch Isolation + Late-Binding ID**:
+
+```mermaid
+flowchart TD
+    A[New Requirement: sa-spec new --name cart --branch] --> B[Create & switch to feat/cart branch<br/>Draft directory: project/cart/]
+    B --> C[AI Analysis: sca<br/>Uses {{REQ_ID}} placeholder<br/>Pre-check against master spec baseline]
+    C --> D{User Approved?<br/>Execute scc or finalize}
+    D --> E[Query latest sequential ID N from master]
+    E --> F[Rename to project/REQ-N+1-cart/<br/>Substitute {{REQ_ID}} with actual ID]
+    F --> G[sa-spec reindex: Dynamically rebuild index.md]
+    G --> H[Merge into master: Zero conflicts, Continuous IDs!]
+```
+
+1. **Draft Phase (No ID Contention)**: Run `sa-spec new --name checkout --branch` to create `feat/checkout` and `project/checkout/` using `{{REQ_ID}}`. Parallel branches never collide. If an idea is abandoned, deleting the branch leaves zero ghost IDs.
+2. **Baseline Protection**: `spec:analyze` fetches latest `master` before analyzing to prevent missing newly merged API or table changes.
+3. **Late-Binding Finalize**: Running `sa-spec finalize --name checkout` inspects master's latest ID, renames the folder, replaces placeholders, and updates `index.md`.
+4. **Conflict-Free Reindex**: `sa-spec reindex` builds `project/index.md` on the fly from disk.
+
+---
+
+## Internationalization (i18n)
+
+`sa-spec` supports 5 primary languages:
+
+| Code | Language | Text & Style Guideline | Technical Terminology Rule |
+|---|---|---|---|
+| `en` | **English** | 100% standard technical English | Standard technical English |
+| `zh-TW` | **繁體中文** (Default) | Traditional Chinese (Taiwan terminology) | Retain native English terms (`REST API`, `Webhook`, `JWT`) |
+| `zh-CN` | **简体中文** | Simplified Chinese (Mainland terminology) | Retain native English terms (`REST API`, `Webhook`, `JWT`) |
+| `ja` | **日本語** | Japanese technical prose with Katakana loanwords | Retain native English terms (`REST API`, `Webhook`, `JWT`) |
+| `ko` | **한국어** | Korean technical prose with standard honorifics | Retain native English terms (`REST API`, `Webhook`, `JWT`) |
+
+### Core Rules:
+1. **Init-Time Language Lock**: Set via `sa-spec init --lang en` or selected interactively upon `spec:init`.
+2. **Single-Language Purity**: The entire project must strictly adhere to the declared language.
+3. **Technical Terms in Native English**: In non-English modes, standard industry terms (`REST API`, `Webhook`, `JWT`, `OAuth 2.0`, `Payload`, `Idempotency Key`, `Redis`, `UUID`) must remain in native English without awkward literal translations.
+4. **Upgrade Protection**: `sa-spec upgrade` automatically detects and respects existing project language without overwriting.
+
+---
+
+## AI Developer Handoff
+
+Once a requirement is finalized via `scc`, pass `handoff.md` to your development agent:
+
+```text
+Please read project/REQ-001-login/handoff.md first as the primary implementation entry point.
+Refer to srs.md, uml/, openapi.yaml, and db-schema.md in the same directory for detailed contracts.
+Do not invent unconfirmed roles, APIs, or database columns.
+```
+
+---
+
+## License
+
+MIT © [lovius](https://github.com/lovius215)

package/README.ja.md

@@ -0,0 +1,143 @@
+# sa-spec - システム分析 AI ワークスペース
+
+[![npm version](https://img.shields.io/npm/v/@loviusc/sa-spec.svg)](https://www.npmjs.com/package/@loviusc/sa-spec)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> 要件やアイデアを、確認可能・監査可能・コンフリクト検出可能なエンジニアリング仕様書へと整理する、AI主導開発向けシステム分析（SA）ドキュメント・ワークスペース。
+
+<p align="center">
+  <b>🌐 言語ナビゲーション (Languages):</b>
+  <a href="./README.en.md"><b>English</b></a> |
+  <a href="./README.zh-TW.md"><b>繁體中文</b></a> |
+  <a href="./README.zh-CN.md"><b>简体中文</b></a> |
+  <a href="./README.ja.md"><b>日本語</b></a> |
+  <a href="./README.ko.md"><b>한국어</b></a>
+</p>
+
+---
+
+## 概要
+
+`sa-spec` は単なる AI ドキュメント生成ツールではなく、**AI コーディング前に行う「システム分析（System Analysis）ワークスペース」** です。
+
+OpenSpec、Claude Code、OpenAI Codex、Gemini CLI などの AI 開発ツールがコード実装を始める前に、要件のスコープ、境界線、データモデル、API 規約、権限マトリクス、受入条件を事前に明確化し、安全で堅牢な開発境界を定義します。
+
+AI ワークフローは 4 つの標準コマンド（エイリアス対応）で動作します：
+
+| コマンド | エイリアス | 目的 | 説明 |
+|---|---|---|---|
+| `spec:init` | `sci` | 初期化 | `AGENTS.md`、ルールセット、指定言語のプロンプトを読み込みます。 |
+| `spec:propose` | `scp` | 要件提案 | 既存の仕様を変更せず、目的・概要・初期フロー・確認事項を整理します。 |
+| `spec:analyze` | `sca` | 分析と起草 | 既存の要件、API、DB スキーマとの競合をチェックし、問題がなければ SRS、UML、OpenAPI、DB スキーマのドラフトを作成します。 |
+| `spec:commit` | `scc` | 確認と保存 | ユーザーが承認したバージョンを正式に採番・保存し、インデックスを更新して Git コミットを作成します。 |
+
+各要件フォルダーには以下の標準成果物が生成されます：
+
+```text
+project/
+  REQ-001-login/
+    srs.md           # ソフトウェア要件仕様書 (SRS)
+    uml/
+      main.puml      # 独立した PlantUML 図（1ファイル1図の原則）
+    openapi.yaml     # OpenAPI 3.0 ドラフト
+    db-schema.md     # データベーススキーマ仕様書
+    handoff.md       # AI 開発ツール向け引き継ぎ要約 (OpenSpec / Claude Code エントリポイント)
+    history.md       # 変更履歴および意思決定ログ
+```
+
+---
+
+## 設計思想
+
+```text
+sa-spec が仕様と境界を明確にし、AI 開発ツールが正しく実装する。
+```
+
+1. **防御的な影響評価**: `spec:analyze` は競合チェックを強制します。新しい要件が既存の権限、API シグネチャ、DB テーブルを意図せず上書き・破壊しないかを厳密に検証します。
+2. **決定論的ステートマシン**: `propose -> analyze -> commit` の流れを遵守します。AI が未確認の業務ルールやテーブルカラムを勝手に捏造することを防ぎます。競合が発見された場合は生成を停止し、人間の指示を仰ぎます。
+3. **AI 開発引き継ぎサマリー (`handoff.md`)**: 実装すべき内容、触れてはならない境界、API 契約、受入条件を凝縮し、後続の AI 開発ツールに安全なガイドラインを提供します。
+
+---
+
+## インストールと利用準備
+
+### 前提環境
+- Node.js 18 以上
+- npm
+- Git
+
+### グローバルインストール
+
+```bash
+npm install -g @loviusc/sa-spec
+```
+
+インストールの確認：
+
+```bash
+sa-spec help
+sa-spec --version
+```
+
+---
+
+## CLI コマンド一覧
+
+| コマンド | 説明 |
+|---|---|
+| `sa-spec init [--full] [--lang <lang>]` | ワークスペースの骨格を初期化します（`zh-TW`、`en`、`zh-CN`、`ja`、`ko` に対応）。 |
+| `sa-spec new [--id REQ-001] --name login [--branch]` | 要件テンプレートを作成します。`--id` を省略すると、Git 分岐を活用したドラフトモード（`feat/<name>`）で開始します。 |
+| `sa-spec finalize --name login` | ドラフト要件に最新の連続番号を割り当て、フォルダー名を変更し、`{{REQ_ID}}` を置換してインデックスを再生成します。 |
+| `sa-spec reindex` | `project/REQ-*` ディレクトリをスキャンし、数値順にソートされた `project/index.md` を自動再構築します。 |
+| `sa-spec check` | 必須ファイルとシステム仕様の状態を検証します。 |
+| `sa-spec status` | 要件とシステム仕様の概要ステータスを表示します。 |
+| `sa-spec doctor` | ワークスペースの依存関係と整合性を診断します。 |
+| `sa-spec upgrade [--dry-run]` | 既存の言語設定を保持したまま、ルールとスキルを最新版にアップグレードします。 |
+
+---
+
+## チーム開発と Git-Flow（遅延採番アーキテクチャ）
+
+複数人での並行開発時に発生する「要件番号の競合」や「Git マージコンフリクト」を防ぐため、**Feature Branch 隔離 + 遅延バインディング（Late-Binding ID）** を採用しています：
+
+```mermaid
+flowchart TD
+    A[要件提案: sa-spec new --name cart --branch] --> B[feat/cart ブランチを作成して切替<br/>ドラフトディレクトリ: project/cart/]
+    B --> C[AI による分析: sca<br/>内部で {{REQ_ID}} プレースホルダー使用<br/>master の最新仕様との競合予防チェック]
+    C --> D{ユーザー承認?<br/>scc または finalize を実行}
+    D --> E[master から最新の利用可能番号 N を取得]
+    E --> F[project/REQ-N+1-cart/ にリネーム<br/>{{REQ_ID}} を正式番号に一括置換]
+    F --> G[sa-spec reindex: index.md を動的に再生成]
+    G --> H[master へマージ: 競合ゼロ、連番維持！]
+```
+
+1. **ドラフト時は番号を奪い合わない**: `sa-spec new --name cart --branch` でブランチを切り、`{{REQ_ID}}` を使って作業します。途中で要件を破棄する場合も、ブランチを削除するだけで済み、欠番（ゴーストID）を残しません。
+2. **基線同期で競合見落としを防止**: `spec:analyze` の実行前に master の最新状態を取得し、他メンバーがマージした最新の API やテーブル変更を反映して競合チェックを行います。
+3. **マージ確定時に正式採番**: `sa-spec finalize` または `scc` で master 上の最新番号を取得してリネームします。
+4. **インデックスのコンフリクト解消**: `sa-spec reindex` でディレクトリから常に決定論的に `project/index.md` を再構築します。
+
+---
+
+## 国際化（i18n）対応
+
+`sa-spec` は 5 つの主要言語を正式にサポートしています：
+
+| コード | 言語名 | 文体・表記ガイドライン | 技術用語の取り扱い原則 |
+|---|---|---|---|
+| `ja` | **日本語** | 日本語技術文体（です/ます、またはである調） | 業界標準の英語用語を維持（`REST API`, `Webhook`, `JWT`） |
+| `en` | **English** | 100% 標準的な技術英文 | 原文の標準英語 |
+| `zh-TW` | **繁體中文** (既定) | 台湾の標準的な技術用語 | 業界標準の英語用語を維持（`REST API`, `Webhook`, `JWT`） |
+| `zh-CN` | **简体中文** | 中国本土の標準的な技術用語 | 業界標準の英語用語を維持（`REST API`, `Webhook`, `JWT`） |
+| `ko` | **한국어** | 韓国語の専門技術文体と敬語 | 業界標準の英語用語を維持（`REST API`, `Webhook`, `JWT`） |
+
+### 重要ルール：
+1. **初期化時の言語確定**: `sa-spec init --lang ja` または `spec:init` 時に対話形式で言語を決定し、`project/system-spec.md` に記録します。
+2. **単一言語の一貫性**: プロジェクト内の全仕様書は選択した言語に統一されます。
+3. **技術専門用語の英語表記維持**: 非英語モードであっても、標準的な技術用語（`REST API`、`Webhook`、`JWT`、`OAuth 2.0`、`Payload`、`Idempotency Key`、`Redis` など）は無理な直訳を避け、**原語の英語表記を強制維持**します。
+4. **アップグレード時の言語保護**: `sa-spec upgrade` は既存プロジェクトの言語を自動検知し、言語設定を勝手に変更しません。
+
+---
+
+## ライセンス
+
+MIT © [lovius](https://github.com/lovius215)

package/README.ko.md

@@ -0,0 +1,143 @@
+# sa-spec - 시스템 분석 AI 워크스페이스
+
+[![npm version](https://img.shields.io/npm/v/@loviusc/sa-spec.svg)](https://www.npmjs.com/package/@loviusc/sa-spec)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> 요구사항과 아이디어를 검증 가능하고, 감사 가능하며, 충돌 검사가 완료된 엔지니어링 기술 사양서로 정리하는 AI 기반 개발용 시스템 분석(SA) 문서 워크스페이스입니다.
+
+<p align="center">
+  <b>🌐 언어 선택 (Languages):</b>
+  <a href="./README.en.md"><b>English</b></a> |
+  <a href="./README.zh-TW.md"><b>繁體中文</b></a> |
+  <a href="./README.zh-CN.md"><b>简体中文</b></a> |
+  <a href="./README.ja.md"><b>日本語</b></a> |
+  <a href="./README.ko.md"><b>한국어</b></a>
+</p>
+
+---
+
+## 개요
+
+`sa-spec`은 단순한 AI 문서 생성 도구가 아니라, **AI 개발 착수 전의 "시스템 분석(System Analysis) 워크스페이스"** 입니다.
+
+OpenSpec, Claude Code, OpenAI Codex, Gemini CLI 등 코드 생성 AI 도구가 구현을 시작하기 전에, 요구사항의 범위, 경계, 데이터 모델, API 인터페이스, 권한 매트릭스, 인수 조건을 사전에 명확히 정의하여 후속 개발이 안전하고 명확한 경계 내에서 진행되도록 보장합니다.
+
+AI 워크플로는 4가지 표준 명령어(별칭 지원)를 기반으로 동작합니다:
+
+| 표준 명령어 | 별칭 | 단계 | 설명 |
+|---|---|---|---|
+| `spec:init` | `sci` | 초기화 | `AGENTS.md`, 시스템 규칙 및 지정된 언어 프롬프트를 로드합니다. |
+| `spec:propose` | `scp` | 요구사항 제안 | 기존 사양을 변경하지 않고 목표, 요약, 초기 흐름 및 미확인 사항을 정리합니다. |
+| `spec:analyze` | `sca` | 분석 및 초안 작성 | 기존 요구사항, API, DB와의 충돌 여부를 검사하고, 문제가 없을 때만 SRS, UML, OpenAPI, DB Schema 초안을 작성합니다. |
+| `spec:commit` | `scc` | 확인 및 보관 | 사용자가 승인한 버전을 정식 번호로 보관하고, 인덱스를 갱신하며 로컬 Git 커밋을 생성합니다. |
+
+보관된 각 요구사항은 독립적이고 완전한 폴더로 구성됩니다:
+
+```text
+project/
+  REQ-001-login/
+    srs.md           # 소프트웨어 요구사항 명세서 (SRS)
+    uml/
+      main.puml      # 독립 PlantUML 다이어그램 (파일당 1개 다이어그램 원칙)
+    openapi.yaml     # OpenAPI 3.0 사양 초안
+    db-schema.md     # 데이터베이스 스키마 및 마이그레이션 정의
+    handoff.md       # AI 개발 도구 인수인계 요약 (OpenSpec / Claude Code 진입점)
+    history.md       # 버전 이력 및 설계 결정 감사 로그
+```
+
+---
+
+## 설계 철학
+
+```text
+sa-spec이 요구사항과 경계를 명확히 정의하고, AI 개발 도구가 올바르게 구현합니다.
+```
+
+1. **방어적 영향도 평가**: `spec:analyze`는 충돌 검사를 강제합니다. 새로운 요구사항이 기존의 역할, 권한, API 서명, 데이터베이스 테이블을 무단으로 변경하지 않는지 사전에 철저히 검증합니다.
+2. **결정론적 상태 머신**: `propose -> analyze -> commit` 흐름을 엄격히 준수합니다. AI가 확인되지 않은 비즈니스 가설이나 테이블 컬럼을 임의로 날조(환각)하는 것을 방지하며, 충돌 발생 시 즉시 생성을 중단하고 사용자 확인을 요청합니다.
+3. **AI 개발 인수인계서 (`handoff.md`)**: 구현해야 할 내용, 변경해서는 안 되는 경계, API 계약 및 인수 조건을 간결하게 정리하여 개발 AI 도구의 안전한 나침반 역할을 수행합니다.
+
+---
+
+## 설치 및 준비
+
+### 필수 환경
+- Node.js 18 이상
+- npm
+- Git
+
+### npm 글로벌 설치
+
+```bash
+npm install -g @loviusc/sa-spec
+```
+
+설치 확인:
+
+```bash
+sa-spec help
+sa-spec --version
+```
+
+---
+
+## CLI 명령어 안내
+
+| 명령어 | 설명 |
+|---|---|
+| `sa-spec init [--full] [--lang <lang>]` | 워크스페이스 골격을 생성합니다 (`zh-TW`, `en`, `zh-CN`, `ja`, `ko` 지원, 기본값 `zh-TW`). |
+| `sa-spec new [--id REQ-001] --name login [--branch]` | 요구사항 템플릿 폴더를 생성합니다. `--id` 생략 시 다중 사용자 초안 브랜치(`feat/<name>`)로 생성됩니다. |
+| `sa-spec finalize --name login` | 초안 요구사항에 최신 연속 번호를 할당하고 폴더명 변경, `{{REQ_ID}}` 치환 및 인덱스를 자동 재구축합니다. |
+| `sa-spec reindex` | `project/REQ-*` 디렉토리를 스캔하여 번호순으로 정렬된 `project/index.md`를 동적으로 재생성합니다. |
+| `sa-spec check` | 필수 파일과 시스템 사양 상태를 검증합니다. |
+| `sa-spec status` | 요구사항 및 시스템 사양 현황을 확인합니다. |
+| `sa-spec doctor` | 워크스페이스 무결성 및 필수 의존 파일을 진단합니다. |
+| `sa-spec upgrade [--dry-run]` | 기존 프로젝트의 언어 설정을 유지하면서 규칙과 스킬을 최신 버전으로 업그레이드합니다. |
+
+---
+
+## 팀 협업 및 Git-Flow (지연 바인딩 아키텍처)
+
+팀 내 동시 병렬 개발 시 발생하는 "일련번호 충돌" 및 "Git 머지 컨플릭트"를 해결하기 위해 **Feature Branch 격리 + 지연 바인딩(Late-Binding ID)** 방식을 적용했습니다:
+
+```mermaid
+flowchart TD
+    A[요구사항 제안: sa-spec new --name cart --branch] --> B[feat/cart 브랜치 생성 및 전환<br/>초안 디렉토리: project/cart/]
+    B --> C[AI 분석 및 초안: sca<br/>내부에서 {{REQ_ID}} 플레이스홀더 사용<br/>master 최신 사양 기반 충돌 검사]
+    C --> D{사용자 승인 완료?<br/>scc 또는 finalize 실행}
+    D --> E[master에서 최신 사용 가능 번호 N 확인]
+    E --> F[project/REQ-N+1-cart/ 폴더명 변경<br/>{{REQ_ID}}를 공식 번호로 일괄 치환]
+    F --> G[sa-spec reindex: index.md 동적 재생성]
+    G --> H[master로 머지: 충돌 제로, 연속된 번호 유지!]
+```
+
+1. **초안 단계 번호 미선점**: `sa-spec new --name cart --branch` 명령으로 독립 브랜치를 생성하고 `{{REQ_ID}}` 플레이스홀더를 사용합니다. 요구사항이 중도 폐기되어도 브랜치만 삭제하면 되며, 결번(고스트 번호)이 발생하지 않습니다.
+2. **사양 기준선 동기화**: `spec:analyze` 실행 전 master의 최신 상태를 동기화하여 다른 팀원이 머지한 API나 테이블과의 충돌 누락을 방지합니다.
+3. **머지 시점 공식 채번**: `sa-spec finalize` 또는 `scc` 실행 시점에 master의 최신 번호를 부여받아 폴더명을 확정합니다.
+4. **인덱스 머지 충돌 제거**: `sa-spec reindex` 명령으로 디렉토리 상태에서 `project/index.md`를 언제든 완벽하게 재생성합니다.
+
+---
+
+## 국제화 (i18n) 지원
+
+`sa-spec`은 5가지 주요 언어를 지원합니다:
+
+| 코드 | 언어 | 텍스트 및 스타일 규격 | 전문 기술 용어 원칙 |
+|---|---|---|---|
+| `ko` | **한국어** | 한국어 전문 기술 문체 및 경어 | 업계 표준 영어 용어 유지 (`REST API`, `Webhook`, `JWT`) |
+| `en` | **English** | 100% 표준 기술 영어 | 원문 표준 영어 |
+| `zh-TW` | **繁體中文** (기본값) | 대만 표준 기술 용어 | 업계 표준 영어 용어 유지 (`REST API`, `Webhook`, `JWT`) |
+| `zh-CN` | **简体中文** | 중국 본토 표준 기술 용어 | 업계 표준 영어 용어 유지 (`REST API`, `Webhook`, `JWT`) |
+| `ja` | **日本語** | 일본어 기술 문체 및 가타카나 외래어 | 업계 표준 영어 용어 유지 (`REST API`, `Webhook`, `JWT`) |
+
+### 핵심 원칙:
+1. **초기화 시점 언어 고정**: `sa-spec init --lang ko` 또는 `spec:init` 시점에 대화형으로 선택하여 `project/system-spec.md`에 기록합니다.
+2. **단일 언어의 순수성**: 프로젝트 내의 모든 사양 문서는 선택된 언어로 100% 통일됩니다.
+3. **기술 전문 용어의 영어 유지**: 비영어권 모드에서도 업계 표준 기술 용어(`REST API`, `Webhook`, `JWT`, `OAuth 2.0`, `Payload`, `Idempotency Key`, `Redis` 등)는 억지 번역을 지양하고 **원문 영어를 강제 유지**합니다.
+4. **업그레이드 보호**: `sa-spec upgrade` 실행 시 기존 프로젝트의 언어 설정을 자동으로 감지하여 유지합니다.
+
+---
+
+## 라이선스
+
+MIT © [lovius](https://github.com/lovius215)

package/README.zh-CN.md

@@ -0,0 +1,143 @@
+# sa-spec - 个人系统分析 AI 工作台
+
+[![npm version](https://img.shields.io/npm/v/@loviusc/sa-spec.svg)](https://www.npmjs.com/package/@loviusc/sa-spec)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> 轻量级、防御性的系统分析文档工作台。通过固定流程把业务想法整理为可确认、可归档、可检查的技术规格文档，为 AI 辅助开发提供明确边界。
+
+<p align="center">
+  <b>🌐 语言导航 (Languages):</b>
+  <a href="./README.en.md"><b>English</b></a> |
+  <a href="./README.zh-TW.md"><b>繁體中文</b></a> |
+  <a href="./README.zh-CN.md"><b>简体中文</b></a> |
+  <a href="./README.ja.md"><b>日本語</b></a> |
+  <a href="./README.ko.md"><b>한국어</b></a>
+</p>
+
+---
+
+## 核心概述
+
+`sa-spec` 的定位不是单纯的 AI 文档生成器，而是 **AI 开发前的系统分析工作台**。
+
+在 OpenSpec、Claude Code、OpenAI Codex、Gemini CLI 等代码生成工具介入之前，`sa-spec` 先行厘清需求边界、业务规则、数据模型、API 契约、权限矩阵与验收条件，避免 AI 编码时随心所欲破坏系统架构。
+
+AI 工作流使用四个标准指令（支持简写别名）：
+
+| 标准指令 | 简写 | 阶段 | 说明 |
+|---|---|---|---|
+| `spec:init` | `sci` | 初始化 | 加载 `AGENTS.md`、系统分析规则与指定语言的规范文件。 |
+| `spec:propose` | `scp` | 提出需求 | 整理需求摘要、目标、初步流程与待确认事项，不修改已有规格。 |
+| `spec:analyze` | `sca` | 分析与起草 | 检查新需求是否与既有需求、API、DB 发生冲突；无冲突才产出 SRS、UML、OpenAPI 与 DB Schema 草案。 |
+| `spec:commit` | `scc` | 确认归档 | 用户确认后正式定号归档，更新索引与系统总表，并自动创建本地 Git commit。 |
+
+每个归档的需求固定包含一个独立完整的文件夹：
+
+```text
+project/
+  REQ-001-login/
+    srs.md           # 软件需求规格说明书 (SRS)
+    uml/
+      main.puml      # 独立 PlantUML 图（单文件单图原则）
+    openapi.yaml     # OpenAPI 3.0 接口草案
+    db-schema.md     # 数据库表结构与变更说明
+    handoff.md       # AI 开发者交接摘要 (面向 OpenSpec / Claude Code)
+    history.md       # 版本历程与设计决策审计记录
+```
+
+---
+
+## 设计理念
+
+```text
+sa-spec 先把需求说清楚、定好边界；AI 代码工具再把需求实现出来。
+```
+
+1. **防御性影响评估**：`spec:analyze` 强制执行冲突检查。特别关注新需求是否会无意间篡改既有角色、权限、API 签名或数据表字段，规避线上安全隐患与逻辑破坏。
+2. **确定性状态机**：遵循 `propose -> analyze -> commit` 状态流转。严禁 AI 凭空臆造未确认的业务规则。发现冲突必须立即暂停，交由人工厘清。
+3. **AI 开发交接摘要 (`handoff.md`)**：提炼已确认的规则、禁止触碰的边界、API 规范与验收标准，作为后续 AI 编码工具的统一入口。
+
+---
+
+## 安装与快速上手
+
+### 环境准备
+- Node.js 18 或以上
+- npm
+- Git
+
+### 全局安装
+
+```bash
+npm install -g @loviusc/sa-spec
+```
+
+验证安装：
+
+```bash
+sa-spec help
+sa-spec --version
+```
+
+---
+
+## CLI 指令一览
+
+| 指令 | 说明 |
+|---|---|
+| `sa-spec init [--full] [--lang <lang>]` | 初始化工作台骨架（支持 `zh-TW`、`en`、`zh-CN`、`ja`、`ko`，默认 `zh-TW`）。 |
+| `sa-spec new [--id REQ-001] --name login [--branch]` | 创建需求模板文件夹。省略 `--id` 时自动切入多人协作草稿分支（`feat/<name>`）。 |
+| `sa-spec finalize --name login` | 将草稿需求正式定号归档为最新序号，自动重命名目录、替换 `{{REQ_ID}}` 并重构索引。 |
+| `sa-spec reindex` | 扫描 `project/REQ-*` 目录，按序数字顺序动态重新生成 `project/index.md`。 |
+| `sa-spec check` | 检查项目必要文件与规格完整性。 |
+| `sa-spec status` | 查看系统规格与需求总览状态。 |
+| `sa-spec doctor` | 诊断工作区环境与必要文件依赖。 |
+| `sa-spec upgrade [--dry-run]` | 将规则与技能升级至最新版，自动保留原语言与历史上下文。 |
+
+---
+
+## 多人协作与 Git-Flow（延迟绑定序号）
+
+为解决团队多人并行开发时“序号争抢”与“Git 合并冲突”的痛点，`sa-spec` 采用 **Feature Branch 隔离 + 延迟定号机制（Late-Binding ID）**：
+
+```mermaid
+flowchart TD
+    A[提出需求: sa-spec new --name cart --branch] --> B[建立并切换至 feat/cart 分支<br/>创建草稿目录 project/cart/]
+    B --> C[AI 分析与起草: sca<br/>内部使用 {{REQ_ID}} 占位<br/>自动同步 master 最新规格防冲突]
+    C --> D{用户确认通过<br/>执行 scc 或 finalize}
+    D --> E[向 master 查询最新可用序号 N]
+    E --> F[重命名为 project/REQ-N+1-cart/<br/>批量替换 {{REQ_ID}} 为正式编号]
+    F --> G[sa-spec reindex: 动态重构 index.md]
+    G --> H[合并回 master: 零冲突、序号连续！]
+```
+
+1. **草稿不抢号**：在分支开发时使用 `project/cart/` 与 `{{REQ_ID}}` 占位符。多人同时提出需求互不冲突。如果需求放弃，直接删除分支，**绝不遗留幽灵跳号**。
+2. **基线同步防漏检**：执行 `spec:analyze` 前先确认同步远端 master 规格，确保以全系统最新状态进行冲突检查。
+3. **归档时原子定号**：执行 `sa-spec finalize` 或 `scc` 时向 master 申请下一个号（例如 `REQ-003`），批量替换并更新。
+4. **动态重建索引**：`sa-spec reindex` 随时可由目录动态排序生成总表，消除 `index.md` 的 merge conflict。
+
+---
+
+## 国际化多语言支持（i18n）
+
+`sa-spec` 完整支持 5 种主要语言：
+
+| 语系代码 | 语言名称 | 文本风格规范 | 专有名词处理惯例 |
+|---|---|---|---|
+| `zh-CN` | **简体中文** | 中国大陆技术用语（如：项目、服务器、支持、默认） | 强制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+| `en` | **English** | 100% 标准技术英文，无中/日/韩字符 | 原生标准英文 |
+| `zh-TW` | **繁體中文** (默认) | 台湾地区技术常用语（如：專案、伺服器、支援） | 强制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+| `ja` | **日本語** | 日语标准技术文体与 Katakana 外来词 | 强制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+| `ko` | **한국어** | 韩语专业技术文体与标准敬语 | 强制保留原生英文（如 `REST API`, `Webhook`, `JWT`） |
+
+### 核心规范：
+1. **初始化锁死**：通过 `sa-spec init --lang zh-CN` 或在 `spec:init` 交互式提示中选定，写入 `project/system-spec.md`。
+2. **全项目语言纯粹**：同一项目内所有需求规格必须 100% 使用该语言，不得杂糅。
+3. **技术专有名词保留原生英文**：非英语系模式下，业界公认的成熟技术术语（如 `REST API`, `Webhook`, `JWT`, `OAuth 2.0`, `Payload`, `Idempotency Key`, `Redis` 等）**强制保持原生英文，禁止生硬直译**。
+4. **升级保护**：执行 `sa-spec upgrade` 时自动继承既有项目语言，不打扰用户。
+
+---
+
+## 开源协议
+
+MIT © [lovius](https://github.com/lovius215)