openfeel 1.2.0 → 1.2.3

package/README.en.md

@@ -65,7 +65,7 @@ openfeel flow status
 > Coexists with the opencode adapter; **disabled by default** (requires explicit `--tools claude`).
 
 - **Enable**: `openfeel setup --tools claude` (or `--tools opencode,claude` for both harnesses).
-- **Assets deployed to `~/.claude/`**: `CLAUDE.md` (global constraints, managed-region three-state; existing user content is appended, not overwritten), `agents/` (**9**, incl. `feel`), `skills/` (**18** shared sources), `settings.json` (injects `"agent":"feel"` + `"permissions":{"defaultMode":"auto"}`; **existing user keys preserved verbatim**).
+- **Assets deployed to `~/.claude/`**: `CLAUDE.md` (global constraints, managed-region three-state; existing user content is appended, not overwritten), `agents/` (**10**, incl. `feel`), `skills/` (**22** shared sources), `settings.json` (injects `"agent":"feel"` + `"permissions":{"defaultMode":"auto"}`; **existing user keys preserved verbatim**; **created when absent, never overwritten** — the user-sovereign `model` key is not rewritten).
 - **Upgrade**: `npm i -g openfeel@latest` → `openfeel setup --tools claude`; **after the first creation of `~/.claude/{agents,skills}`, restart the session or run `/reload-skills`** to load new skills/agents; `CLAUDE.md` takes effect on the **next session**. `npm i -g` alone does not refresh global assets.
 - **Zero-touch by default**: without `--tools`, `~/.claude/` is **unchanged**.
 
@@ -74,21 +74,62 @@ openfeel flow status
 > **Coexists** with the full pipeline; new deployments default to **fast** (`config.yaml defaults.workflow_mode`), overridable per stage.
 
 - **Fast line**: `plan_pending → plan_review → plan_passed → exec_running → review_pending → review_passed → archiving → done` (skips 6 phases: `scheme_*` / `test_*`; **plan review and code review each keep a single round**; `review_failed` loops back for retries).
-- **Choose and switch**: `openfeel plan stage add <name> --workflow-mode full|fast` (new stage); `openfeel stage set <stage> --workflow-mode full|fast` (per-stage switch); `openfeel config set defaults.workflow_mode full|fast` (project-level default memory).
-- **Inspect (read-only)**: `openfeel flow mode [--stage <id>] [--json]` (current mode + source); `openfeel flow phases [--mode full|fast] [--stage <id>]` (view the transition table per mode).
+- **Choose and switch**: `openfeel plan stage add <name> --workflow-mode full|fast|general` (new stage); `openfeel stage set <stage> --workflow-mode full|fast|general` (per-stage switch); `openfeel config set defaults.workflow_mode full|fast|general` (project-level default memory). **`general` is requirement-level only** (since v1.2.1; see "What's New in v1.2.1").
+- **Inspect (read-only)**: `openfeel flow mode [--stage <id>] [--json]` (current mode + source); `openfeel flow phases [--mode full|fast|general] [--stage <id>]` (view the transition table per mode).
 - **Auto-advance enabled by default**: new deployments default to `auto_advance: enabled` (since v1.1.7); to disable: `openfeel config set auto_advance disabled`.
 
 Upgrade/migration notes: see [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) ("工作流模式（full / fast）与自动推进" section, Chinese) and [CHANGELOG.md](CHANGELOG.md) `[1.1.7]`.
 
+## Fixes in v1.2.3 (Patch)
+
+> Stage covered: **stage-99**. This patch closes the items carried out of v1.2.2 and adds no new features; the 33 successful exports / 34 registered options contract and exit-code semantics are unchanged. This repository's closure baseline: **75 test files / 1911 cases / 21 stages**.
+
+- **Unified concurrent JSON exit (REV-95-009)**: the `handleConcurrentConflict` JSON branch now emits the `FLOW_CONCURRENT_CONFLICT` envelope, sets `process.exitCode=2`, and returns (same mechanism as `failCli`, avoiding stdout truncation on Windows pipes); the non-JSON branch is unchanged verbatim; all 10 call sites return without fallthrough.
+- **`--review-tier` help-text correction (REV-98-003 item 6)**: `flow advance --help` and the zh/en i18n entries now say "default = full (zero pruning)" instead of "derived from the workflow mode"; the mode-derived value is the `flow phases --json.reviewTier` display value; default advance behavior is unchanged.
+- **`req` filter single-sourcing (REV-97-006)**: `req show` / `req set --workflow-mode` reuse `listLinkedStages`; `req split` and the core done primitives remain unchanged; behavior is identical.
+- **Lock-timeout E2E test hook (REV-98-006①, test-only)**: an env seam active only when `OPENFEEL_TEST_MODE=1` makes the timeout path assert `INTERNAL_ERROR/internal/3` deterministically; production defaults remain 5000/3000ms.
+
+## What's New in v1.2.2
+
+> Stages covered: **stage-95 ~ 98**. All capabilities below are **available since v1.2.2**; `docs/json-contract.md` is the single authority for the JSON contract (33 successful exports / 34 registered options). This repository's closure baseline: 74 test files / 1894 cases / 21 stages.
+
+- **`openfeel flow next [--json]` (decision authority, read-only)**: 12 keys in fixed order (`schemaVersion,stage,phase,phaseLabel,responsibleAgent,workflowMode,reviewTier,effectiveReviewTier,legalNextPhases,suggestedCommand,guards,blockingReviews`); `responsibleAgent` shares the same source as `mapPhaseToAgent`; every element of `legalNextPhases` is accepted by `flow advance`; zero writes.
+- **Global `--project <path>`**: leading/trailing/`=` forms before or after any command; semantically equivalent to cwd; language resolves from the target project while `--log-file` relative paths resolve from the original cwd; `knowledge dedup` keeps its local declaration (syntactically compatible).
+- **Full read-command `--json` coverage**: 13 command surfaces (`stage status` / `flow recover` / `flow checkpoint list` / `flow log` / `project overview` / `knowledge search|list|index|dedup` / `config get|effective` / `view list` / `plan scheme list`) plus `archive <stage> --json`; **33 successful exports / 34 registered options** in total.
+- **Machine-readable error envelope**: `{schemaVersion:1,error:{code,kind,message,detail}}`; exit codes **0 success / 1 expected refusal / 2 concurrent conflict / 3 internal error (new)**; legacy `{error:'...'}` keeps the string type and key order, appending `errorKind` at the end; 12-row `code→kind→exitCode` mapping.
+- **`--version --json`**: `{schemaVersion:1,version,node}` (three keys; listed separately, not counted among the 33 exports/34 options).
+- **`flow archive --dry-run --json` criteria details + `archive <stage> --json`**: `eligible` / `unfinishedStages` / `blockingReviews`; `archivePath` / counts; `--dry-run` writes nothing.
+- **`reviewTier` disambiguation**: `flow phases --json` / `flow status.stages[]` / `flow next` now expose both the display value `reviewTier`/`displayReviewTier` and the effective value `effectiveReviewTier` (always `full`). **Correction**: when `flow advance` is not given an explicit `--review-tier`, the effective tier is always **`full`** (not derived from the mode); the mode-derived value is `flow phases --json.reviewTier` (display only). Source help-text correction moves to v1.2.3.
+- **Compatibility promise**: the existing 19 successful export field sets are unbroken (additive only); human output is unchanged verbatim; exit codes 0/1/2 keep their semantics while 3 is new only; the 15-phase enum / `advanceAccepted` / full-fast behavior are unchanged; existing `flow.json` files need zero migration and receive zero injection; REQ-001 L80 ("2 = internal or usage error") is registered as a requirement-text erratum (authoritative wording in contract §2/§10).
+
+## What's New in v1.2.1
+
+> Stages covered: **stage-86 ~ 93 + 94** (94 = out-of-table supplementary stage: model defaults and non-destructive deployment). All capabilities below are **available since v1.2.1**.
+
+- **Three-mode architecture (`full` / `fast` / `general`)**: the `workflow_mode` value domain grows from 2 to 3 values (default remains `fast`). `general` (no pipeline) is **requirement-level only** — stage-level / deployment-level write surfaces reject it (explicit command-layer gates in `plan stage add` / `stage set` / `config set`; wizard offers no such option); the resolution chain gains a "requirement" layer (`status.md > requirement > config.yaml > builtin`); **upgrades only, never implicit downgrades**.
+- **Requirement intake and splitting (`openfeel req split`)**: **splitting publishes** — children enter `scheduled` in one shot; `parent_id` is traceability-only (**not in aggregation / not in the done gate / not in `PATCH_WHITELIST`**); parallel intake (`claim` never blocks); **requirements are decoupled from versions** (`target_version` is display / filter / sort only, never a gate). The `req` command group grows **10 → 11 subcommands**.
+- **Direct dispatch of general workers (two dialects)**: opencode = nested `task` tool; Claude Code = direct Handoff. In general mode any Agent can accept **directly dispatched** execution work.
+- **New agent `openfeel-explorer` (read-only)**: dedicated "research / exploration" route — 4 read-only tools (Read / Glob / Grep / Bash); agent count **9 → 10**.
+- **Observability**: `metrics.json` wired via `recordRun`; CLI logs carry `duration_ms` / `project` / `session_id`; op-level timestamps; cross-session resume marker (`resumed`).
+- **Review tiers (`--review-tier <full|lean|skip>`)**: an axis **orthogonal** to workflow mode — the mode picks the base table, the tier prunes review gates (`full` prunes nothing / `lean` prunes `scheme_review` / `skip` prunes `plan_review + scheme_review`; code review, test and archiving gates are always kept). Defaults derive from the mode (`full`→`full` / `fast`→`lean` / `general`→`full`). `flow phases --json` appends `reviewTier` last (existing 6 keys unchanged verbatim, **7 keys total**).
+- **Parallel orchestration contract + lightweight archiving**.
+- **Unified model defaults + non-destructive deployment (user-sovereign `model` key)**: deployment (`setup` / `update`) **creates the user's `model` key when absent and never overwrites it**.
+
+### Bug Fixes (v1.2.1)
+
+- **`req/BUG-002`**: the **completion path for `general` requirements** — a `general` requirement always has zero linked stages (bidirectional carrier gate) while the done gate demands all linked stages done; the two crossed and left `general` requirements **permanently unable to reach `done`**. A **dual completion path** is now provided (criterion = the requirement's own `workflow_mode` field, same source as the carrier gate), so `req advance --to done` / `req set --status done` **succeed** for stage-less `general` requirements; the single-source rule for non-`general` requirements is unchanged; done-gate rejections use dedicated copy.
+- **`cli/BUG-011`**: tier pruning left a stage **with no transition targets when sitting exactly on a pruned phase**. Pruning now **applies to incoming edges / targets only**, so pruned phases keep their outgoing edges; **entering** a pruned gate remains unreachable.
+- **`templates/BUG-007`**: the en archiver pointer dangled → switched to the Chinese section name, plus a "named § pointer literal hit" assertion to prevent recurrence.
+
 ## What's New in v1.2.0
 
 - **flow.json version-shard archiving (`flow archive`)**: three entry points — `openfeel flow archive <version>` (perform archiving; gate = all stages of that version are done and no blocking open REV; **no `--force`**), `openfeel flow archive list`, `openfeel flow archive show <version> [--json]`; archives land at `.openfeel/flow-archive/{version}.json`. **Distinct from the top-level `openfeel archive <stage>` (stage-summary archiving)**; regular commands do not read archives.
-- **Requirement flow (`openfeel req`)**: 10 subcommands (add / list / show / claim / release / set / link / advance / board / next) + 7 statuses (`draft` / `scheduled` / `in_progress` / `done` / `blocked` / `cancelled` / `rejected`); requirement progress is aggregated from linked stage phases (**auto-closes once all linked stages are done**); claim protocol = `owner` + `claimed_at` (no TTL). Authoritative usage source: the `openfeel-req` skill.
+- **Requirement flow (`openfeel req`)**: 10 subcommands (11 since v1.2.1, +`split`) (add / list / show / claim / release / set / link / advance / board / next) + 7 statuses (`draft` / `scheduled` / `in_progress` / `done` / `blocked` / `cancelled` / `rejected`); requirement progress is aggregated from linked stage phases (**auto-closes once all linked stages are done**); claim protocol = `owner` + `claimed_at` (no TTL). Authoritative usage source: the `openfeel-req` skill.
 - **Compatibility**: legacy flow.json (without `requirements` / `archived_versions`) raises no errors; upgrading **requires no migration**.
 
 ## What's New in v1.1.2
 
-- **Self-description**: `flow phases [--json]` lists all valid phases and the transition table (6 top-level JSON keys: `schemaVersion` / `phases` / `transitions` / `advanceAccepted` / `transitionsDiff` / `workflowMode` (added in v1.1.7; existing five keys unchanged verbatim)).
+- **Self-description**: `flow phases [--json]` lists all valid phases and the transition table (6 top-level JSON keys: `schemaVersion` / `phases` / `transitions` / `advanceAccepted` / `transitionsDiff` / `workflowMode` (added in v1.1.7; existing five keys unchanged verbatim); **7 keys since v1.2.1**, appending `reviewTier` last).
 - **Stage governance**: `flow stage remove` / `plan stage add --deps` / `stageId` validation and directory-conflict detection.
 - **Effective config**: `config effective` prints the resolved value plus its source (`status.md > config.yaml > profile.yaml > builtin`).
 - **Structured output**: `flow status/current/health/metrics/overview --json` (pure JSON + `schemaVersion`).
@@ -144,7 +185,7 @@ Feel is the command center, receiving user intent and dispatching downstream Age
 
 ### Global Deployment and Workspace Layering
 
-Framework assets (9 agents / 18 skills / global `AGENTS.md` / global `opencode.jsonc`) are deployed to `~/.config/opencode/` via `openfeel setup`; **the repository itself keeps no project-level `.opencode/agents|skills`** (since stage-55).
+Framework assets (10 agents / 22 skills / global `AGENTS.md` / global `opencode.jsonc`) are deployed to `~/.config/opencode/` via `openfeel setup`; **the repository itself keeps no project-level `.opencode/agents|skills`** (since stage-55).
 
 Workspace state is layered into two files: `current.md` (team file, cross-user overall progress, ≤5 entries + auto-archiving) and `dev_last.md` (local index + topic directory, cross-session recovery). Framework assets are **automatically backed up** before deployment overwrite to `~/.openfeel/backup/{ts}/`.
 
@@ -201,14 +242,14 @@ Core Layer
   └── workspace/ — Directory structure & knowledge base
 ```
 
-> **Global asset deployment**: 9 agents / 18 skills / global `AGENTS.md` / global `opencode.jsonc` are deployed to `~/.config/opencode/` via `openfeel setup`; the repository itself keeps no project-level `.opencode/agents|skills` (since stage-55).
+> **Global asset deployment**: 10 agents / 22 skills / global `AGENTS.md` / global `opencode.jsonc` are deployed to `~/.config/opencode/` via `openfeel setup`; the repository itself keeps no project-level `.opencode/agents|skills` (since stage-55).
 
 ## Development
 
 ```bash
 npm install        # Install dependencies
 npm run build      # Compile TypeScript
-npm test           # Run tests (1557 cases / 70 test files; Linux CI skips 1 Windows-only case)
+npm test           # Run tests (1894 cases / 74 test files; Linux CI skips 1 Windows-only case)
 ```
 
 ## Acknowledgments

package/README.md

@@ -8,7 +8,7 @@
 
 OpenFeel 是一个 TypeScript CLI 工具，为 AI Agent 开发提供端到端的流程治理。核心理念：**「提示词瘦身，流程入工具」** —— Agent 不靠读长文本理解流程，而是通过 `flow.json` 获取当前状态和下一步指令。
 
-> 📦 **最新版本 v1.2.0**（flow.json 版本分片归档 / 需求流转系统） — 归档 `flow archive`（版本分片）+ 需求 `openfeel req`（10 子命令 / 7 状态）；既有自描述 `flow phases`、配置有效值 `config effective`、部署前自动备份要点保留。
+> 📦 **最新版本 v1.2.3**（v1.2.2 转出项收口 · 补丁） — 并发 JSON 退出机制统一（emit → `process.exitCode=2` → return）+ `flow advance --help --review-tier` 文案订正（缺省=full 零裁剪）+ `req show` / `req set` 过滤单点化 + 锁等待超时 E2E 测试钩子（test-only）。**33 个成功出口 / 34 个注册选项**契约与退出码 0/1/2/3 语义不变。
 
 > 📌 本项目基于 [AI_Prompt](https://github.com/Liuary/AI_Prompt) 开发，参考了 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 等工具的设计思路。
 
@@ -35,7 +35,7 @@ npm install -g openfeel@latest # 更新到最新版本
 > 与 opencode 适配器**并存**，**默认不启用**（须显式 `--tools claude`）。
 
 - **启用**：`openfeel setup --tools claude`（或 `--tools opencode,claude` 双 harness）。
-- **部署资产到 `~/.claude/`**：`CLAUDE.md`（全局约束，受管区三态，用户已有内容 append 不覆盖）、`agents/`（**9 个**，含 `feel`）、`skills/`（**18 个**共享源）、`settings.json`（注入 `"agent":"feel"` + `"permissions":{"defaultMode":"auto"}`，**用户既有键逐字保留**）。
+- **部署资产到 `~/.claude/`**：`CLAUDE.md`（全局约束，受管区三态，用户已有内容 append 不覆盖）、`agents/`（**10 个**，含 `feel`）、`skills/`（**22 个**共享源）、`settings.json`（注入 `"agent":"feel"` + `"permissions":{"defaultMode":"auto"}`，**用户既有键逐字保留**；**无则创建、有则不覆盖**——用户主权键 `model` 不被改写）。
 - **升级**：`npm i -g openfeel@latest` → `openfeel setup --tools claude`；**首次创建 `~/.claude/{agents,skills}` 后须重启会话或 `/reload-skills`** 使新 skill/agent 生效；`CLAUDE.md` 于**下次会话**生效。仅 `npm i -g` 不刷新全局资产。
 - **默认零触**：不带 `--tools` 时 `~/.claude/` **零变化**。
 
@@ -44,14 +44,55 @@ npm install -g openfeel@latest # 更新到最新版本
 > 与完整流水线（full）**并存**；新部署默认 **fast**（`config.yaml defaults.workflow_mode`），可逐阶段覆盖与切回。
 
 - **快线链**：`plan_pending → plan_review → plan_passed → exec_running → review_pending → review_passed → archiving → done`（跳过 6 项 `scheme_*` / `test_*`；**计划审查与代码审查保留单轮**，`review_failed` 可回环重试）。
-- **选择与切换**：`openfeel plan stage add <name> --workflow-mode full|fast`（新建阶段）；`openfeel stage set <stage> --workflow-mode full|fast`（单阶段切回）；`openfeel config set defaults.workflow_mode full|fast`（项目默认记忆）。
-- **查看（只读）**：`openfeel flow mode [--stage <id>] [--json]`（当前模式 + 来源）；`openfeel flow phases [--mode full|fast] [--stage <id>]`（按模式查看转移表）。
+- **选择与切换**：`openfeel plan stage add <name> --workflow-mode full|fast|general`（新建阶段）；`openfeel stage set <stage> --workflow-mode full|fast|general`（单阶段切回）；`openfeel config set defaults.workflow_mode full|fast|general`（项目默认记忆）。**`general` 仅需求级合法**（v1.2.1 起，见下「v1.2.1 新增能力」）。
+- **查看（只读）**：`openfeel flow mode [--stage <id>] [--json]`（当前模式 + 来源）；`openfeel flow phases [--mode full|fast|general] [--stage <id>]`（按模式查看转移表）。
 - **默认自动推进开启**：新部署默认 `auto_advance: enabled`（v1.1.7 起）；如需关闭：`openfeel config set auto_advance disabled`。
 
+## v1.2.3 修复（补丁）
+
+> 对应阶段：**stage-99**。本版为 v1.2.2 转出项收口，不新增功能；JSON 契约 33 成功出口 / 34 注册选项与退出码语义不变。本仓收口基线：**75 文件 / 1911 用例 / 21 阶段**。
+
+- **并发 JSON 退出机制统一（REV-95-009）**：`handleConcurrentConflict` JSON 分支改为「输出 `FLOW_CONCURRENT_CONFLICT` envelope → 置 `process.exitCode=2` → return」（与 `failCli` 同机制，规避 Windows 管道 stdout 截断）；非 JSON 分支 `console.error + process.exit(2)` 逐字不变；10 个调用点无 fallthrough。
+- **`--review-tier` help 文案订正（REV-98-003 第 6 项）**：`flow advance --help` 与 i18n zh/en 由「缺省=按模式派生」改为「缺省=full（零裁剪）」；按模式派生的是 `flow phases --json.reviewTier` 展示值；缺省推进行为不变。
+- **`req` 过滤单点化（REV-97-006）**：`req show` / `req set --workflow-mode` 复用 `listLinkedStages`；`req split` 与 core 引擎层 done 判定原语保留；行为零变化。
+- **锁等待超时 E2E 测试钩子（REV-98-006①，test-only）**：仅 `OPENFEEL_TEST_MODE=1` 生效的 env seam 使超时路径可稳定断言 `INTERNAL_ERROR/internal/3`；生产默认 5000/3000ms 不变。
+
+## v1.2.2 新增能力
+
+> 对应阶段：**stage-95 ~ 98**。以下能力**v1.2.2 起提供**；JSON 契约单一权威见 docs/json-contract.md（33 个成功出口 / 34 个注册选项）。本仓收口基线：74 文件 / 1894 用例 / 21 阶段。
+
+- **`openfeel flow next [--json]`（决策权威，只读）**：12 键固定序（`schemaVersion,stage,phase,phaseLabel,responsibleAgent,workflowMode,reviewTier,effectiveReviewTier,legalNextPhases,suggestedCommand,guards,blockingReviews`）；`responsibleAgent` 与 `mapPhaseToAgent` 同源；`legalNextPhases` 每个元素均被 `flow advance` 接受；零写盘。
+- **全局 `--project <path>`**：任意命令前置/后置/`=` 形态；语义等效 cwd；语言按目标项目、`--log-file` 相对路径按原始 cwd；`knowledge dedup` 保留本地声明（语法兼容）。
+- **读命令 `--json` 全量补全**：13 个命令面（`stage status` / `flow recover` / `flow checkpoint list` / `flow log` / `project overview` / `knowledge search|list|index|dedup` / `config get|effective` / `view list` / `plan scheme list`）+ `archive <stage> --json`；累计 **33 个成功出口 / 34 个注册选项**。
+- **机器可读错误封装**：`{schemaVersion:1,error:{code,kind,message,detail}}`；退出码 **0 成功 / 1 预期拒绝 / 2 并发冲突 / 3 内部错误（新增）**；legacy `{error:'...'}` 保留 string 类型与键序、末尾追加 `errorKind`；12 行 `code→kind→exitCode` 映射表。
+- **`--version --json`**：`{schemaVersion:1,version,node}`（三键；单列，不计入 33 出口/34 选项）。
+- **`flow archive --dry-run --json` 判据明细 + `archive <stage> --json`**：`eligible` / `unfinishedStages` / `blockingReviews`；`archivePath` / 计数；`--dry-run` 零写盘。
+- **`reviewTier` 消歧**：`flow phases --json` / `flow status.stages[]` / `flow next` 同时给出展示值 `reviewTier`/`displayReviewTier` 与生效值 `effectiveReviewTier`（恒 `full`）。**订正**：`flow advance` 未显式传 `--review-tier` 时生效档位恒 **`full`**（不是按模式派生）；按模式派生的是 `flow phases --json.reviewTier` 展示值。源码 help 文案订正转 v1.2.3。
+- **兼容承诺**：既有 19 个成功出口字段零破坏（只增不改）；人类输出逐字不变；退出码 0/1/2 语义不变、3 仅新增；phase 枚举 15 项 / `advanceAccepted` / full-fast 行为不变；存量 `flow.json` 零迁移零注入；REQ-001 L80「2=内部错误或用法错误」登记为需求文本勘误（权威口径见契约 §2/§10）。
+
+## v1.2.1 新增能力
+
+> 对应阶段：**stage-86 ~ 93 + 94**（94 = 表外补阶段：模型默认值与部署非破坏性）。以下能力**v1.2.1 起提供**。
+
+- **三模式架构（`full` / `fast` / `general`）**：`workflow_mode` 值域由 2 值扩为 3 值（默认仍 `fast`）。`general`（无流水线）**仅需求级合法**——阶段级 / 部署级写入面拒绝（`plan stage add` / `stage set` / `config set` 命令层显式门 + wizard 不提供选项）；模式解析链增「需求级」一层（`status.md > 需求级 > config.yaml > builtin`）；**升级不降级**（可 `general` → `fast` / `full`，反向无隐式动作）。
+- **需求接取与拆分（`openfeel req split`）**：**拆分即发布**——子需求一次入 `scheduled`；`parent_id` 仅溯源（**不入聚合 / 不入 done 门 / 不参与 `PATCH_WHITELIST`**）；并行接取（`claim` 互不阻塞）；**需求与版本解绑**（`target_version` 为纯展示 / 过滤 / 排序维度，非门）。`req` 命令组 **10 → 11 子命令**（`split` = 首个 repeatable option、首个带 `--json` 的写命令）；`req advance --to done` 语义见下「缺陷修复」。
+- **通用工作者直接调度（双口径）**：opencode 侧 = 嵌套 `task` 工具；Claude Code 侧 = Handoff 直发。通用模式下可承接任意 Agent **直接调度**的执行任务（不限于流水线 op）。
+- **新 agent `openfeel-explorer`（只读）**：专职「调研 / 探索」路由——只读 4 工具（Read / Glob / Grep / Bash），不产出源码变更；agent 数 **9 → 10**。
+- **可观测性**：`metrics.json` 经 `recordRun` 接线；CLI 日志含 `duration_ms` / `project` / `session_id` 三字段；op 级时间戳；跨会话恢复标注（`resumed`）。
+- **审查档位（`--review-tier <full|lean|skip>`）**：与工作流模式**分属两轴**——模式定基表，档位裁审查关（`full` = 零裁剪 / `lean` 裁 `scheme_review` / `skip` 裁 `plan_review + scheme_review`；恒保留代码审查关 / 测试关 / 归档关）。缺省按模式派生（`full`→`full` / `fast`→`lean` / `general`→`full`）；显式 `lean` / `skip` 打印一行非阻断警告。`flow phases --json` 末位追加 `reviewTier`（既有 6 键逐字保留，**共 7 键**）。
+- **并行编排契约 + 归档轻量化**：阶段并行互不阻塞；归档段与轻量化步骤分离。
+- **模型默认值统一 + 部署非破坏性（用户主权键 `model`）**：opencode 侧显式默认收敛为 `deepseek/deepseek-flash`；部署（`setup` / `update`）对用户既有 `model` 键**无则创建、有则不覆盖**——不与用户既有值双写漂移。
+
+### 缺陷修复（v1.2.1）
+
+- **`req/BUG-002`**：`general` 需求**完成路径**——`general` 恒零关联阶段（载体制双向门）而 done 门要求全部关联阶段 done，两者交叉曾致 `general` 需求**永远无法 `done`**（死锁）。现开辟**载体制对偶完成路径**（判据 = 需求自身 `workflow_mode` 字段直判，与载体制门同源），`openfeel req advance --to done` / `req set --status done` 对零关联 `general` 需求**放行**；非 `general` 需求判定单源不变；done 门拒绝改用专用文案。
+- **`cli/BUG-011`**：审查档位裁剪致**当前相位无跳转目标**——阶段恰停于被裁剪相位时该档位无可达目标。现**裁剪只作用于入边 / 目标侧**，被裁剪相位保留出边（可正常向该档位下游推进）；「进入被裁剪关」仍不可达。
+- **`templates/BUG-007`**：en 归档官指针悬空（`§Archive Mechanical Checklist` → 目标节仅中文）→ 改中文节名，并补「具名 § 指针字面命中」断言防再犯。
+
 ## v1.2.0 新增能力
 
 - **flow.json 版本分片归档（`flow archive`）**：三个入口——`openfeel flow archive <version>`（执行归档；判据门 = 该版本全部阶段 done 且无 blocking open REV，**不设 `--force`**）、`openfeel flow archive list`、`openfeel flow archive show <version> [--json]`；归档落点 `.openfeel/flow-archive/{version}.json`。**与顶层 `openfeel archive <stage>`（阶段摘要归档）区分**；常规命令不读归档。
-- **需求流转（`openfeel req`）**：10 子命令（`add` / `list` / `show` / `claim` / `release` / `set` / `link` / `advance` / `board` / `next`）+ 7 状态（`draft` / `scheduled` / `in_progress` / `done` / `blocked` / `cancelled` / `rejected`）；需求进度由关联阶段 phase 聚合（**全部关联阶段 done 时自动收口**）；认领协议 = `owner` + `claimed_at`（无 TTL）。用法权威源见 `openfeel-req` skill。
+- **需求流转（`openfeel req`）**：10 子命令（v1.2.1 起 11，+`split`）（`add` / `list` / `show` / `claim` / `release` / `set` / `link` / `advance` / `board` / `next`）+ 7 状态（`draft` / `scheduled` / `in_progress` / `done` / `blocked` / `cancelled` / `rejected`）；需求进度由关联阶段 phase 聚合（**全部关联阶段 done 时自动收口**）；认领协议 = `owner` + `claimed_at`（无 TTL）。用法权威源见 `openfeel-req` skill。
 - **兼容**：旧 flow.json（无 `requirements` / `archived_versions`）零报错，升级**无需迁移**。
 
 完整中文文档：[README.zh-CN.md](README.zh-CN.md)（详见其中的「Claude Code 适配器」小节）

package/README.zh-CN.md

@@ -65,7 +65,7 @@ openfeel flow status
 > 与 opencode 适配器**并存**，**默认不启用**（须显式 `--tools claude`）。
 
 - **启用**：`openfeel setup --tools claude`（或 `--tools opencode,claude` 双 harness）。
-- **部署资产到 `~/.claude/`**：`CLAUDE.md`（全局约束，受管区三态，用户已有内容 append 不覆盖）、`agents/`（**9 个**，含 `feel`）、`skills/`（**18 个**共享源）、`settings.json`（注入 `"agent":"feel"` + `"permissions":{"defaultMode":"auto"}`，**用户既有键逐字保留**）。
+- **部署资产到 `~/.claude/`**：`CLAUDE.md`（全局约束，受管区三态，用户已有内容 append 不覆盖）、`agents/`（**10 个**，含 `feel`）、`skills/`（**22 个**共享源）、`settings.json`（注入 `"agent":"feel"` + `"permissions":{"defaultMode":"auto"}`，**用户既有键逐字保留**；**无则创建、有则不覆盖**——用户主权键 `model` 不被改写）。
 - **升级**：`npm i -g openfeel@latest` → `openfeel setup --tools claude`；**首次创建 `~/.claude/{agents,skills}` 后须重启会话或 `/reload-skills`** 使新 skill/agent 生效；`CLAUDE.md` 于**下次会话**生效。仅 `npm i -g` 不刷新全局资产。
 - **默认零触**：不带 `--tools` 时 `~/.claude/` **零变化**。
 
@@ -74,21 +74,62 @@ openfeel flow status
 > 与完整流水线（full）**并存**；新部署默认 **fast**（`config.yaml defaults.workflow_mode`），可逐阶段覆盖与切回。
 
 - **快线链**：`plan_pending → plan_review → plan_passed → exec_running → review_pending → review_passed → archiving → done`（跳过 6 项 `scheme_*` / `test_*`；**计划审查与代码审查保留单轮**，`review_failed` 可回环重试）。
-- **选择与切换**：`openfeel plan stage add <name> --workflow-mode full|fast`（新建阶段）；`openfeel stage set <stage> --workflow-mode full|fast`（单阶段切回）；`openfeel config set defaults.workflow_mode full|fast`（项目默认记忆）。
-- **查看（只读）**：`openfeel flow mode [--stage <id>] [--json]`（当前模式 + 来源）；`openfeel flow phases [--mode full|fast] [--stage <id>]`（按模式查看转移表）。
+- **选择与切换**：`openfeel plan stage add <name> --workflow-mode full|fast|general`（新建阶段）；`openfeel stage set <stage> --workflow-mode full|fast|general`（单阶段切回）；`openfeel config set defaults.workflow_mode full|fast|general`（项目默认记忆）。**`general` 仅需求级合法**（v1.2.1 起，见下「v1.2.1 新增能力」）。
+- **查看（只读）**：`openfeel flow mode [--stage <id>] [--json]`（当前模式 + 来源）；`openfeel flow phases [--mode full|fast|general] [--stage <id>]`（按模式查看转移表）。
 - **默认自动推进开启**：新部署默认 `auto_advance: enabled`（v1.1.7 起）；如需关闭：`openfeel config set auto_advance disabled`。
 
 升级迁移提示见 [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)「工作流模式（full / fast）与自动推进」小节与 [CHANGELOG.md](CHANGELOG.md) `[1.1.7]`。
 
+## v1.2.3 修复（补丁）
+
+> 对应阶段：**stage-99**。本版为 v1.2.2 转出项收口，不新增功能；JSON 契约 33 成功出口 / 34 注册选项与退出码语义不变。本仓收口基线：**75 文件 / 1911 用例 / 21 阶段**。
+
+- **并发 JSON 退出机制统一（REV-95-009）**：`handleConcurrentConflict` JSON 分支改为「输出 envelope → 置 `process.exitCode=2` → return」；非 JSON 分支逐字不变；10 个调用点无 fallthrough。
+- **`--review-tier` help 文案订正（REV-98-003 第 6 项）**：源码 help 与 i18n zh/en 改为「缺省=full（零裁剪）」；缺省推进行为不变。
+- **`req` 过滤单点化（REV-97-006）**：`req show` / `req set --workflow-mode` 复用 `listLinkedStages`；`req split` 与 core 引擎层 done 判定原语保留。
+- **锁等待超时 E2E 测试钩子（REV-98-006①，test-only）**：仅 `OPENFEEL_TEST_MODE=1` 生效；生产默认 5000/3000ms 不变；E2E 断言 `INTERNAL_ERROR/internal/3`。
+
+## v1.2.2 新增能力
+
+> 对应阶段：**stage-95 ~ 98**。以下能力**v1.2.2 起提供**；JSON 契约单一权威见 docs/json-contract.md（33 个成功出口 / 34 个注册选项）。本仓收口基线：74 文件 / 1894 用例 / 21 阶段。
+
+- **`openfeel flow next [--json]`（决策权威，只读）**：12 键固定序（`schemaVersion,stage,phase,phaseLabel,responsibleAgent,workflowMode,reviewTier,effectiveReviewTier,legalNextPhases,suggestedCommand,guards,blockingReviews`）；`responsibleAgent` 与 `mapPhaseToAgent` 同源；`legalNextPhases` 每个元素均被 `flow advance` 接受；零写盘。
+- **全局 `--project <path>`**：任意命令前置/后置/`=` 形态；语义等效 cwd；语言按目标项目、`--log-file` 相对路径按原始 cwd；`knowledge dedup` 保留本地声明（语法兼容）。
+- **读命令 `--json` 全量补全**：13 个命令面（`stage status` / `flow recover` / `flow checkpoint list` / `flow log` / `project overview` / `knowledge search|list|index|dedup` / `config get|effective` / `view list` / `plan scheme list`）+ `archive <stage> --json`；累计 **33 个成功出口 / 34 个注册选项**。
+- **机器可读错误封装**：`{schemaVersion:1,error:{code,kind,message,detail}}`；退出码 **0 成功 / 1 预期拒绝 / 2 并发冲突 / 3 内部错误（新增）**；legacy `{error:'...'}` 保留 string 类型与键序、末尾追加 `errorKind`；12 行 `code→kind→exitCode` 映射表。
+- **`--version --json`**：`{schemaVersion:1,version,node}`（三键；单列，不计入 33 出口/34 选项）。
+- **`flow archive --dry-run --json` 判据明细 + `archive <stage> --json`**：`eligible` / `unfinishedStages` / `blockingReviews`；`archivePath` / 计数；`--dry-run` 零写盘。
+- **`reviewTier` 消歧**：`flow phases --json` / `flow status.stages[]` / `flow next` 同时给出展示值 `reviewTier`/`displayReviewTier` 与生效值 `effectiveReviewTier`（恒 `full`）。**订正**：`flow advance` 未显式传 `--review-tier` 时生效档位恒 **`full`**（不是按模式派生）；按模式派生的是 `flow phases --json.reviewTier` 展示值。源码 help 文案订正转 v1.2.3。
+- **兼容承诺**：既有 19 个成功出口字段零破坏（只增不改）；人类输出逐字不变；退出码 0/1/2 语义不变、3 仅新增；phase 枚举 15 项 / `advanceAccepted` / full-fast 行为不变；存量 `flow.json` 零迁移零注入；REQ-001 L80「2=内部错误或用法错误」登记为需求文本勘误（权威口径见契约 §2/§10）。
+
+## v1.2.1 新增能力
+
+> 对应阶段：**stage-86 ~ 93 + 94**（94 = 表外补阶段：模型默认值与部署非破坏性）。以下能力**v1.2.1 起提供**。
+
+- **三模式架构（`full` / `fast` / `general`）**：`workflow_mode` 值域由 2 值扩为 3 值（默认仍 `fast`）。`general`（无流水线）**仅需求级合法**——阶段级 / 部署级写入面拒绝（`plan stage add` / `stage set` / `config set` 命令层显式门 + wizard 不提供选项）；模式解析链增「需求级」一层（`status.md > 需求级 > config.yaml > builtin`）；**升级不降级**。
+- **需求接取与拆分（`openfeel req split`）**：**拆分即发布**——子需求一次入 `scheduled`；`parent_id` 仅溯源（**不入聚合 / 不入 done 门 / 不参与 `PATCH_WHITELIST`**）；并行接取（`claim` 互不阻塞）；**需求与版本解绑**（`target_version` 为纯展示 / 过滤 / 排序维度，非门）。`req` 命令组 **10 → 11 子命令**。
+- **通用工作者直接调度（双口径）**：opencode 侧 = 嵌套 `task` 工具；Claude Code 侧 = Handoff 直发。通用模式下可承接任意 Agent **直接调度**的执行任务。
+- **新 agent `openfeel-explorer`（只读）**：专职「调研 / 探索」路由——只读 4 工具（Read / Glob / Grep / Bash）；agent 数 **9 → 10**。
+- **可观测性**：`metrics.json` 经 `recordRun` 接线；CLI 日志含 `duration_ms` / `project` / `session_id` 三字段；op 级时间戳；跨会话恢复标注（`resumed`）。
+- **审查档位（`--review-tier <full|lean|skip>`）**：与工作流模式**分属两轴**——模式定基表，档位裁审查关（`full` 零裁剪 / `lean` 裁 `scheme_review` / `skip` 裁 `plan_review + scheme_review`；恒保留代码审查关 / 测试关 / 归档关）。缺省按模式派生（`full`→`full` / `fast`→`lean` / `general`→`full`）。`flow phases --json` 末位追加 `reviewTier`（既有 6 键逐字保留，**共 7 键**）。
+- **并行编排契约 + 归档轻量化**。
+- **模型默认值统一 + 部署非破坏性（用户主权键 `model`）**：部署（`setup` / `update`）对用户既有 `model` 键**无则创建、有则不覆盖**。
+
+### 缺陷修复（v1.2.1）
+
+- **`req/BUG-002`**：`general` 需求**完成路径**——`general` 恒零关联阶段（载体制双向门）而 done 门要求全部关联阶段 done，两者交叉曾致 `general` 需求**永远无法 `done`**。现开辟**载体制对偶完成路径**（判据 = 需求自身 `workflow_mode` 字段直判，与载体制门同源），`req advance --to done` / `req set --status done` 对零关联 `general` 需求**放行**；非 `general` 判定单源不变；done 门拒绝改用专用文案。
+- **`cli/BUG-011`**：审查档位裁剪致**当前相位无跳转目标**。现**裁剪只作用于入边 / 目标侧**，被裁剪相位保留出边；「进入被裁剪关」仍不可达。
+- **`templates/BUG-007`**：en 归档官指针悬空 → 改中文节名 + 补「具名 § 指针字面命中」断言。
+
 ## v1.2.0 新增能力
 
 - **flow.json 版本分片归档（`flow archive`）**：三个入口——`openfeel flow archive <version>`（执行归档；判据门 = 该版本全部阶段 done 且无 blocking open REV，**不设 `--force`**）、`openfeel flow archive list`、`openfeel flow archive show <version> [--json]`；归档落点 `.openfeel/flow-archive/{version}.json`。**与顶层 `openfeel archive <stage>`（阶段摘要归档）区分**；常规命令不读归档。
-- **需求流转（`openfeel req`）**：10 子命令（`add` / `list` / `show` / `claim` / `release` / `set` / `link` / `advance` / `board` / `next`）+ 7 状态（`draft` / `scheduled` / `in_progress` / `done` / `blocked` / `cancelled` / `rejected`）；需求进度由关联阶段 phase 聚合（**全部关联阶段 done 时自动收口**）；认领协议 = `owner` + `claimed_at`（无 TTL）。用法权威源见 `openfeel-req` skill。
+- **需求流转（`openfeel req`）**：10 子命令（v1.2.1 起 11，+`split`）（`add` / `list` / `show` / `claim` / `release` / `set` / `link` / `advance` / `board` / `next`）+ 7 状态（`draft` / `scheduled` / `in_progress` / `done` / `blocked` / `cancelled` / `rejected`）；需求进度由关联阶段 phase 聚合（**全部关联阶段 done 时自动收口**）；认领协议 = `owner` + `claimed_at`（无 TTL）。用法权威源见 `openfeel-req` skill。
 - **兼容**：旧 flow.json（无 `requirements` / `archived_versions`）零报错，升级**无需迁移**。
 
 ## v1.1.2 新增能力
 
-- **自描述**：`flow phases [--json]` 输出全部合法 phase 与转移表（JSON 顶层 6 键：`schemaVersion` / `phases` / `transitions` / `advanceAccepted` / `transitionsDiff` / `workflowMode`（v1.1.7 追加，既有五键语义逐字不变））。
+- **自描述**：`flow phases [--json]` 输出全部合法 phase 与转移表（JSON 顶层 6 键：`schemaVersion` / `phases` / `transitions` / `advanceAccepted` / `transitionsDiff` / `workflowMode`（v1.1.7 追加，既有五键语义逐字不变）；v1.2.1 起 7 键，末位追加 `reviewTier`）。
 - **阶段治理**：`flow stage remove` / `plan stage add --deps` / `stageId` 校验与目录冲突检测。
 - **配置有效值**：`config effective` 输出有效值 + 生效来源（`status.md > config.yaml > profile.yaml > builtin`）。
 - **结构化输出**：`flow status/current/health/metrics/overview --json`（纯 JSON + `schemaVersion`）。
@@ -144,7 +185,7 @@ Feel 是整个流程的调度中心，负责接收用户意图并调度下游 Ag
 
 ### 全局部署与工作区分层
 
-框架资产（9 agent / 18 skill / 全局 `AGENTS.md` / 全局 `opencode.jsonc`）经 `openfeel setup` 部署到 `~/.config/opencode/`；**仓库自身不保留项目级 `.opencode/agents|skills`**（stage-55 起）。
+框架资产（10 agent / 22 skill / 全局 `AGENTS.md` / 全局 `opencode.jsonc`）经 `openfeel setup` 部署到 `~/.config/opencode/`；**仓库自身不保留项目级 `.opencode/agents|skills`**（stage-55 起）。
 
 工作区状态分两层：`current.md`（团队文件，跨用户整体进度，≤5 条 + 自动归档）与 `dev_last.md`（本地索引 + 主题目录，跨会话恢复）。框架资产部署覆盖前**自动备份**至 `~/.openfeel/backup/{ts}/`。
 
@@ -201,14 +242,14 @@ Core 层
   └── workspace/ — 目录结构和知识库
 ```
 
-> **框架资产全局部署**：9 agent / 18 skill / 全局 `AGENTS.md` / 全局 `opencode.jsonc` 经 `openfeel setup` 部署到 `~/.config/opencode/`；仓库自身不保留项目级 `.opencode/agents|skills`（stage-55 起）。
+> **框架资产全局部署**：10 agent / 22 skill / 全局 `AGENTS.md` / 全局 `opencode.jsonc` 经 `openfeel setup` 部署到 `~/.config/opencode/`；仓库自身不保留项目级 `.opencode/agents|skills`（stage-55 起）。
 
 ## 开发
 
 ```bash
 npm install        # 安装依赖
 npm run build      # 编译 TypeScript
-npm test           # 运行测试（1557 用例 / 70 个测试文件；Linux CI 跳过 1 个 Windows 专属用例）
+npm test           # 运行测试（1894 用例 / 74 个测试文件；Linux CI 跳过 1 个 Windows 专属用例）
 ```
 
 ## 致谢

package/bin/openfeel.js

@@ -3,12 +3,13 @@
 // 无参数时进入 REPL 交互模式，有参数时正常 CLI 模式
 import { program, applyHelpI18n, startRepl, runCli } from '../dist/cli/index.js';
 import { installOutputEncoding } from '../dist/cli/output-encoding.js';
-import { installRuntimeLog } from '../dist/core/runtime-log.js';
+import { installRuntimeLog, installExitHooks } from '../dist/core/runtime-log.js';
 
 const args = process.argv.slice(2);
-// 进程入口安装：输出编码 + 运行日志（单一咽喉；库/测试侧未调用即 no-op）
+// 进程入口安装：输出编码 + 运行日志 + 退出兜底（单一咽喉；库/测试侧未调用即 no-op）
 installOutputEncoding();
 installRuntimeLog();
+installExitHooks();
 // 在 parse 前注入翻译，此时命令树已就绪
 applyHelpI18n(program);
 if (args.length === 0) {

package/dist/cli/index.d.ts

@@ -20,9 +20,23 @@ export declare function shouldUseColor(options?: {
 export declare function applyHelpI18n(program: Command): void;
 /** 并发写冲突退出码：与通用错误 1 区分，便于自动化识别「可重试」冲突 */
 export declare const EXIT_CONCURRENT = 2;
-/** 统一 CLI 错误处理：识别 flow.json 并发写冲突并输出可重试提示（单点，T38） */
-export declare function handleCliError(err: unknown): never;
-/** CLI 启动入口：包裹 program.parse，统一处理并发写冲突 */
+/**
+ * 统一 CLI 错误处理（单点，T38；stage-95 op-002 扩展 JSON 模式）。
+ * 分类优先级：并发冲突（exit 2）→ Commander 用法错误（JSON：INVALID_ARGUMENT/1）→ 其他（JSON：INTERNAL_ERROR/3）。
+ * 非 JSON 模式：并发冲突与用法错误保持既有形态；其他异常输出堆栈并置 exit 3（本版新增内部错误码）。
+ * @param err 捕获到的异常
+ */
+export declare function handleCliError(err: unknown): void;
+/**
+ * CLI 启动入口：JSON 模式单点预扫描 + `--project` 项目锚定 + 统一 catch（并发 / 用法错误 / 内部错误）。
+ *
+ * 顺序契约（stage-95 op-003，严格）：
+ * 1. `setJsonMode` —— 错误输出模式须在 `--project` 失败前已知；
+ * 2. `--version --json` 短路 —— 纯信息命令，不进入 Commander、不依赖项目（非法 `--project` 不阻断）；
+ *    `--help --json` 不拦截（帮助文本保持）；
+ * 3. `applyProjectOption` —— 预扫描 + 单点 chdir，必须早于 `logCliStart`（日志 project 字段 = 目标项目）；
+ * 4. `logCliStart` → `emitGlobalDeployCheck` → `program.parse` → `logCliDone`。
+ */
 export declare function runCli(): void;
 export { program };
 export { startRepl } from './repl.js';

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAe9B;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAYrE;AA2CD,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+EpD;AAED,yCAAyC;AACzC,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAQlD;AAED,0CAA0C;AAC1C,wBAAgB,MAAM,IAAI,IAAI,CAY7B;AAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAsBpD,QAAA,MAAM,OAAO,SAAgB,CAAC;AAqC9B;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAYrE;AA2CD,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+EpD;AAED,yCAAyC;AACzC,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAwCjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,IAAI,IAAI,CAgC7B;AAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/cli/index.js

@@ -3,13 +3,15 @@
  * 基于 Commander 构建命令行入口，静态导入并注册所有命令模块。
  * 新增命令只需在 src/commands/ 下创建模块并在本文件末尾追加 import + register 调用。
  */
-import { Command } from 'commander';
+import { Command, CommanderError } from 'commander';
 import { createRequire } from 'node:module';
 import { t, getCliLang, hasKey } from '../core/i18n.js';
 import { isFlowConcurrentError } from '../core/flow-manager.js';
-import { handleConcurrentConflict } from '../commands/shared/errors.js';
-import { runtimeLog } from '../core/runtime-log.js';
+import { emitErrorEnvelope, handleConcurrentConflict } from '../commands/shared/errors.js';
+import { isJsonMode, resolveJsonMode, setJsonMode, resolveVersionFlag, withSchemaVersion, emitJson, } from '../commands/shared/json-output.js';
+import { runtimeLog, logCliStart, logCliDone } from '../core/runtime-log.js';
 import { emitGlobalDeployCheck } from './deploy-check-output.js';
+import { applyProjectOption } from './project-option.js';
 // 读取 package.json 获取版本号
 const require = createRequire(import.meta.url);
 const pkg = require('../../package.json');
@@ -26,7 +28,31 @@ program
     // stage-58 B-4：运行日志全局选项
     .option('--log-file <path>', t('help.global.logFile', getCliLang(process.cwd())))
     .option('--no-log', t('help.global.noLog', getCliLang(process.cwd())))
-    .option('--debug', t('help.global.debug', getCliLang(process.cwd())));
+    .option('--debug', t('help.global.debug', getCliLang(process.cwd())))
+    // stage-95 op-003：全局 --project（预扫描 + 单点 chdir；help 文案语言在模块加载期按原始 cwd 求值）
+    .option('--project <path>', t('help.global.project', getCliLang(process.cwd())));
+// ── stage-95 op-002：Commander 机制（须在子命令注册前安装，子命令创建时继承） ──
+// 用法错误（未知命令/未知选项/缺参）的 JSON 模式封装：
+//  - exitCode===0（--help / --version）放行，走 Commander 原生 process.exit(0)；
+//  - JSON 模式 throw CommanderError → runCli catch 转 INVALID_ARGUMENT envelope + exit 1；
+//  - 非 JSON 模式 process.exit(err.exitCode)，与现状逐字等价。
+program.exitOverride((err) => {
+    if (err.code === 'commander.executeSubCommandAsync')
+        return;
+    if (err.exitCode === 0)
+        return;
+    if (isJsonMode())
+        throw err;
+    process.exit(err.exitCode);
+});
+// JSON 模式下静默 Commander 人类错误文本（防止混入 stdout/stderr）；非 JSON 逐字不变
+program.configureOutput({
+    writeErr: (str) => {
+        if (!isJsonMode()) {
+            process.stderr.write(str);
+        }
+    },
+});
 /**
  * 是否启用彩色输出（B7-1，单一判定入口）。
  * 优先级：`--no-color`（显式关闭，commander 解析为 color=false） > `NO_COLOR` 环境变量（存在且**非空**即关闭，
@@ -166,21 +192,84 @@ export function applyHelpI18n(program) {
 }
 /** 并发写冲突退出码：与通用错误 1 区分，便于自动化识别「可重试」冲突 */
 export const EXIT_CONCURRENT = 2;
-/** 统一 CLI 错误处理：识别 flow.json 并发写冲突并输出可重试提示（单点，T38） */
+/**
+ * 统一 CLI 错误处理（单点，T38；stage-95 op-002 扩展 JSON 模式）。
+ * 分类优先级：并发冲突（exit 2）→ Commander 用法错误（JSON：INVALID_ARGUMENT/1）→ 其他（JSON：INTERNAL_ERROR/3）。
+ * 非 JSON 模式：并发冲突与用法错误保持既有形态；其他异常输出堆栈并置 exit 3（本版新增内部错误码）。
+ * @param err 捕获到的异常
+ */
 export function handleCliError(err) {
     // stage-58 B-6：记录「命令处理中抛出的异常」。error 级语义边界（REV-002）：
     // commander 解析期错误（未知命令/未知选项/缺参）经 program.error() 直接 process.exit(1)，不抛异常、不达此处 → 不入日志。
+    // stage-95 op-002：JSON 模式下解析期错误经 exitOverride throw 后到达此处（记日志，形态无回归）。
     runtimeLog('error', 'cli error: ' + (err instanceof Error ? err.message : String(err)));
     if (isFlowConcurrentError(err)) {
         handleConcurrentConflict(err, getCliLang(process.cwd()));
+        return;
+    }
+    const lang = getCliLang(process.cwd());
+    if (err instanceof CommanderError) {
+        // JSON 模式：用法错误 → INVALID_ARGUMENT envelope + exit 1
+        if (isJsonMode()) {
+            emitErrorEnvelope({
+                code: 'INVALID_ARGUMENT',
+                message: t('common.invalidArgumentTmpl', lang, { detail: err.message }),
+                detail: { commanderCode: err.code },
+            });
+            process.exitCode = 1;
+            return;
+        }
+        // 非 JSON：保持既有未捕获形态（正常路径到不了此处，exitOverride 已 process.exit）
+        throw err;
     }
-    throw err;
+    if (isJsonMode()) {
+        // JSON 模式：其他未捕获异常 → INTERNAL_ERROR envelope + exit 3
+        const msg = err instanceof Error ? err.message : String(err);
+        emitErrorEnvelope({
+            code: 'INTERNAL_ERROR',
+            message: t('common.errorTmpl', lang, { msg }),
+            detail: err instanceof Error
+                ? { name: err.name, message: err.message, stack: err.stack }
+                : { name: 'Error', message: String(err) },
+        });
+        process.exitCode = 3;
+        return;
+    }
+    // 非 JSON：保持既有含堆栈形态，退出码归本版新增的 3（内部错误）
+    console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+    process.exitCode = 3;
 }
-/** CLI 启动入口：包裹 program.parse，统一处理并发写冲突 */
+/**
+ * CLI 启动入口：JSON 模式单点预扫描 + `--project` 项目锚定 + 统一 catch（并发 / 用法错误 / 内部错误）。
+ *
+ * 顺序契约（stage-95 op-003，严格）：
+ * 1. `setJsonMode` —— 错误输出模式须在 `--project` 失败前已知；
+ * 2. `--version --json` 短路 —— 纯信息命令，不进入 Commander、不依赖项目（非法 `--project` 不阻断）；
+ *    `--help --json` 不拦截（帮助文本保持）；
+ * 3. `applyProjectOption` —— 预扫描 + 单点 chdir，必须早于 `logCliStart`（日志 project 字段 = 目标项目）；
+ * 4. `logCliStart` → `emitGlobalDeployCheck` → `program.parse` → `logCliDone`。
+ */
 export function runCli() {
+    // stage-95 op-002：JSON 模式单点（命令层只读 isJsonMode()，不得各自解析 argv）
+    const argv = process.argv.slice(2);
+    setJsonMode(resolveJsonMode(argv));
+    // stage-95 op-003：--version/-v + --json → 单文档并返回（不进入 Commander；纯信息命令）
+    if (resolveVersionFlag(argv) && isJsonMode()) {
+        logCliStart(argv);
+        emitJson(withSchemaVersion({ version: pkg.version, node: process.version }));
+        logCliDone(0);
+        return;
+    }
+    // stage-95 op-003：--project 预扫描必须在 logCliStart 之前（日志 project 字段 = 目标项目）
+    if (!applyProjectOption(argv)) {
+        // JSON 模式 failCli 仅置 process.exitCode 不退出 → 此处 return 保 logCliDone 记录真实码
+        logCliDone(typeof process.exitCode === 'number' ? process.exitCode : 1);
+        return;
+    }
     // stage-58 B-6：命令（argv）+ 结果入运行日志；不记录 stdout 内容。
-    // 注：--help/--version 由 commander 输出后直接 exit → 不记「cli done」；错误路径经 handleCliError 抛出 → 亦不记「cli done」。
-    runtimeLog('info', 'cli start: ' + process.argv.slice(2).join(' '));
+    // 注：--help/--version 经 commander 输出后 exit → 由 exit 兜底记「cli done」（v1.2.1-stage-86 有意变更）；
+    // 错误路径经 handleCliError 置退出码后落到 logCliDone，记录真实退出码。
+    logCliStart(argv);
     // stage-67：被动部署提示（门控内置于适配器；异常静默，不影响主命令）
     emitGlobalDeployCheck();
     try {
@@ -189,7 +278,7 @@ export function runCli() {
     catch (err) {
         handleCliError(err);
     }
-    runtimeLog('info', 'cli done exit=' + (process.exitCode ?? 0));
+    logCliDone(typeof process.exitCode === 'number' ? process.exitCode : 0);
 }
 export { program };
 export { startRepl } from './repl.js';

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EACL,UAAU,EACV,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,GACT,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,wBAAwB;AACxB,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,oBAAoB,CAAwB,CAAC;AAEjE,QAAQ;AACR,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,wBAAwB,CAAC;KACrC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC;IAC/C,uEAAuE;KACtE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,qBAAqB,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC1E,2FAA2F;KAC1F,MAAM,CAAC,uBAAuB,EAAE,CAAC,CAAC,sBAAsB,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC;IAC9F,wBAAwB;KACvB,MAAM,CAAC,mBAAmB,EAAE,CAAC,CAAC,qBAAqB,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;KAChF,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,mBAAmB,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;KACrE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,mBAAmB,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACrE,yEAAyE;KACxE,MAAM,CAAC,kBAAkB,EAAE,CAAC,CAAC,qBAAqB,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAEnF,0DAA0D;AAC1D,iCAAiC;AACjC,wEAAwE;AACxE,uFAAuF;AACvF,mDAAmD;AACnD,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,EAAE,EAAE;IAC3B,IAAI,GAAG,CAAC,IAAI,KAAK,kCAAkC;QAAE,OAAO;IAC5D,IAAI,GAAG,CAAC,QAAQ,KAAK,CAAC;QAAE,OAAO;IAC/B,IAAI,UAAU,EAAE;QAAE,MAAM,GAAG,CAAC;IAC5B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC7B,CAAC,CAAC,CAAC;AACH,8DAA8D;AAC9D,OAAO,CAAC,eAAe,CAAC;IACtB,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE;QAChB,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;YAClB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,OAA6B;IAC1D,qBAAqB;IACrB,IAAI,OAAO,EAAE,KAAK,KAAK,KAAK,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,gCAAgC;IAChC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;IACrC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,0BAA0B;IAC1B,OAAO,IAAI,CAAC;AACd,CAAC;AAED,2BAA2B;AAE3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,2BAA2B,CAAC,OAAO,CAAC,CAAC;AACrC,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,wBAAwB,CAAC,OAAO,CAAC,CAAC;AAClC,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAE5B,qBAAqB;AACrB,+BAA+B;AAC/B,mDAAmD;AACnD,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAEvC;;;OAGG;IACH,SAAS,WAAW,CAAC,IAAY;QAC/B,OAAO,IAAI;aACR,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;aACnB,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED;;OAEG;IACH,SAAS,OAAO,CAAC,GAAY,EAAE,IAAc;QAC3C,MAAM,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAE3C,sCAAsC;QACtC,IAAI,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,SAAS,CAAC;YAC1B,MAAM,cAAc,GAAG,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACxC,IAAI,cAAc,KAAK,OAAO,EAAE,CAAC;gBAC/B,GAAG,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QAED,6DAA6D;QAC7D,oCAAoC;QACpC,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,mBAAmB,IAAI,EAAE,EAAE,CAAC;YAChD,MAAM,MAAM,GAAG,GAAG,SAAS,OAAO,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;YAC/C,IAAI,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;gBACzB,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;QAED,oBAAoB;QACpB,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YAC9B,+CAA+C;YAC/C,IAAK,GAA4B,CAAC,MAAM;gBAAE,SAAS;YACnD,qBAAqB;YACrB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC;YACnC,IAAI,CAAC,IAAI;gBAAE,SAAS;YACpB,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,MAAM,GAAG,GAAG,SAAS,IAAI,OAAO,EAAE,CAAC;YACzC,4CAA4C;YAC5C,IAAI,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;gBACzB,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;QAED,UAAU;QACV,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC/B,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IAED,wBAAwB;IACxB,MAAM,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IACzC,MAAM,cAAc,GAAG,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACxC,IAAI,cAAc,KAAK,OAAO,EAAE,CAAC;QAC/B,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC;IACtC,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAClC,IAAK,GAA4B,CAAC,MAAM;YAAE,SAAS;QACnD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC;QACnC,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,QAAQ,OAAO,CAAC,IAAI,EAAE,IAAI,OAAO,EAAE,CAAC;QACnD,yDAAyD;QACzD,IAAI,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;YACzB,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IACD,yCAAyC;IACzC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACnC,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,yCAAyC;AACzC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,oDAAoD;IACpD,sFAAsF;IACtF,sEAAsE;IACtE,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACxF,IAAI,qBAAqB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,wBAAwB,CAAC,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACzD,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACvC,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;QAClC,oDAAoD;QACpD,IAAI,UAAU,EAAE,EAAE,CAAC;YACjB,iBAAiB,CAAC;gBAChB,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EAAE,CAAC,CAAC,4BAA4B,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;gBACvE,MAAM,EAAE,EAAE,aAAa,EAAE,GAAG,CAAC,IAAI,EAAE;aACpC,CAAC,CAAC;YACH,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,0DAA0D;QAC1D,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,IAAI,UAAU,EAAE,EAAE,CAAC;QACjB,qDAAqD;QACrD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,iBAAiB,CAAC;YAChB,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,CAAC,CAAC,kBAAkB,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC;YAC7C,MAAM,EAAE,GAAG,YAAY,KAAK;gBAC1B,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE;gBAC5D,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE;SAC5C,CAAC,CAAC;QACH,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,qCAAqC;IACrC,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/E,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,MAAM;IACpB,4DAA4D;IAC5D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,WAAW,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IAEnC,sEAAsE;IACtE,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,UAAU,EAAE,EAAE,CAAC;QAC7C,WAAW,CAAC,IAAI,CAAC,CAAC;QAClB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC7E,UAAU,CAAC,CAAC,CAAC,CAAC;QACd,OAAO;IACT,CAAC;IAED,wEAAwE;IACxE,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,yEAAyE;QACzE,UAAU,CAAC,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxE,OAAO;IACT,CAAC;IAED,gDAAgD;IAChD,wFAAwF;IACxF,mDAAmD;IACnD,WAAW,CAAC,IAAI,CAAC,CAAC;IAClB,wCAAwC;IACxC,qBAAqB,EAAE,CAAC;IACxB,IAAI,CAAC;QACH,OAAO,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,cAAc,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IACD,UAAU,CAAC,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/cli/project-option.d.ts

@@ -0,0 +1,40 @@
+/** `--project` 预扫描结果 */
+export interface ProjectArgResult {
+    /** 全部 `--project` 原始取值（按出现顺序；路径解析归 applyProjectOption） */
+    values: string[];
+    /** 是否出现缺值形态（`--project` 末尾/后接选项，或 `--project=` 空值） */
+    missingValue: boolean;
+}
+/**
+ * 提取全部 `--project` 值（含 `--project=`；缺失值置标志）。
+ * @param argv 命令行参数（不含 node 与脚本路径）
+ * @returns 原始取值列表与缺值标志
+ */
+export declare function extractProjectArgs(argv: string[]): ProjectArgResult;
+/**
+ * 单值便捷入口：取最后一个出现值（无则 null）。
+ * 注：多值冲突判定在 applyProjectOption 内完成，本函数仅用于单值场景。
+ * @param argv 命令行参数
+ * @returns 最后一个 `--project` 原始值；未出现返回 null
+ */
+export declare function extractProjectArg(argv: string[]): string | null;
+/**
+ * 预扫描应用：校验并 chdir 到 `--project` 目标目录。
+ * 成功 chdir 返回 true；失败输出错误后返回 false（JSON 模式不 exit，由调用方 return；
+ * 非 JSON 模式 failCli 即时退出，测试 mock exit 时可继续返回 false）。
+ * @param argv 命令行参数
+ * @param originalCwd 原始 cwd（缺省 = process.cwd()；用于 chdir 前的路径/语言解析）
+ * @returns 是否可继续执行
+ */
+export declare function applyProjectOption(argv: string[], originalCwd?: string): boolean;
+/**
+ * 命令层单点解析项目根路径。
+ * 预扫描成功时返回绝对路径（禁止对原始相对值二次 resolve）；直接 parse（测试/库调用）无预扫描时
+ * 回退 `resolve(process.cwd(), raw ?? '.')`，保持既有 `knowledge dedup --project X` 语义。
+ * @param raw 命令层取得的原始 `--project` 值（可为 undefined）
+ * @returns 绝对项目根路径
+ */
+export declare function resolveProjectPathForCommand(raw?: string): string;
+/** 测试隔离：清空预扫描结果（非生产路径） */
+export declare function resetProjectRootForTest(): void;
+//# sourceMappingURL=project-option.d.ts.map

package/dist/cli/project-option.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-option.d.ts","sourceRoot":"","sources":["../../src/cli/project-option.ts"],"names":[],"mappings":"AAuBA,wBAAwB;AACxB,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,sDAAsD;IACtD,YAAY,EAAE,OAAO,CAAC;CACvB;AAKD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAGnE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAG/D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CA0EhF;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED,0BAA0B;AAC1B,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}