openfeel 1.3.2 → 1.3.3

package/README.en.md

@@ -112,6 +112,7 @@ openfeel setup --tools dsh    # 2. Deploy into DSH profiles (all by default; use
 - **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 [docs/VERSIONS.md](docs/VERSIONS.md)).
 - **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`.
+- **v1.3.3 fixes (fast-mode structural gaps)**: fast chain gains a **rework edge** `review_passed → exec_running` (`flow advance --reason "<fix note>"` is audited); fast stages without ops can attach **stage-level REVs** via `flow review add --stage <id>`; the write guard now allows **new files in an uninitialized workspace** and `docs/**` / doc-note paths (source still requires `exec_running`); `plan stage add` now **focuses the stage atomically**. Stage-ID normalization and `plan/` directory mapping: see [docs/commands.md](docs/commands.md).
 
 Upgrade/migration notes: see [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) ("工作流模式（full / fast）与自动推进" section, Chinese) and [CHANGELOG.md](CHANGELOG.md) `[1.1.7]`.
 

package/README.md

@@ -10,7 +10,7 @@
 
 OpenFeel 是一个 TypeScript CLI 工具，为 AI Agent 开发提供端到端的流程治理。核心理念：**「提示词瘦身，流程入工具」** —— Agent 不靠读长文本理解流程，而是通过 `flow.json` 获取当前状态和下一步指令。
 
-> 📦 **最新版本 v1.3.2**（DSH 激活与写入门禁） — 新增 `ctx.tools.guard` 写入门禁与非 OpenFeel 工作区 bootstrap：未初始化时默认 `enforce=always` 会拒绝文件写入，直到 `openfeel init`；`project` / `off` 可 opt-out。版本能力概览见 [docs/VERSIONS.md](docs/VERSIONS.md)。
+> 📦 **最新版本 v1.3.3**（fast 模式结构性修复） — 修复反馈中 13 项结构性问题（12 次实测拒绝）：审查条目可挂阶段（无 op 的 fast 场景）、fast 新增返工边 `review_passed → exec_running`、写入门禁按风险分层（空仓新增 / doc-note 放行）、`plan stage add` 原子聚焦、status.md 派生写、阶段 ID↔目录映射文档化。版本能力概览见 [docs/VERSIONS.md](docs/VERSIONS.md)。
 
 > 📌 本项目基于 [AI_Prompt](https://github.com/Liuary/AI_Prompt) 开发，参考了 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 等工具的设计思路。
 
@@ -82,5 +82,6 @@ openfeel setup --tools dsh    # 2. 部署到 DSH profile（默认全部；可 --
 - **选择与切换**：`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 起，见 [docs/VERSIONS.md](docs/VERSIONS.md)）。
 - **查看（只读）**：`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.3.3 修复（fast 结构性缺口）**：fast 快线新增**返工边** `review_passed → exec_running`（`flow advance --reason` 落审计）；无 op 的 fast 阶段可用 `flow review add --stage <id>` 挂**阶段级 REV**；写入门禁对**空仓新增文件**与 `docs/**` / doc-note 放行（源码仍要求 `exec_running`）；`plan stage add` 后**原子聚焦**。阶段 ID 归一化与 `plan/` 目录映射见 [docs/commands.md](docs/commands.md)。
 
 完整中文文档：[README.zh-CN.md](README.zh-CN.md)（含 Claude Code / DSH 适配器、命令参考与核心概念）

package/README.zh-CN.md

@@ -112,6 +112,7 @@ openfeel setup --tools dsh    # 2. 部署到 DSH profile（默认全部；可 --
 - **选择与切换**：`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 起，见 [docs/VERSIONS.md](docs/VERSIONS.md)）。
 - **查看（只读）**：`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.3.3 修复（fast 结构性缺口）**：fast 快线新增**返工边** `review_passed → exec_running`（`flow advance --reason "<整改原因>"` 落审计）；无 op 的 fast 阶段可用 `flow review add --stage <id>` 挂**阶段级 REV**；写入门禁对**空仓新增文件**与 `docs/**` / doc-note 放行（源码仍要求 `exec_running`）；`plan stage add` 后**原子聚焦**活跃阶段。阶段 ID 归一化与 `plan/` 目录映射见 [docs/commands.md](docs/commands.md)。
 
 升级迁移提示见 [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)「工作流模式（full / fast）与自动推进」小节与 [CHANGELOG.md](CHANGELOG.md) `[1.1.7]`。
 

package/dist/commands/flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../src/commands/flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqgF1D;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,OAAO,EAAE,iBAAiB,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAE9G"}
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../src/commands/flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAslF1D;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,OAAO,EAAE,iBAAiB,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAE9G"}

package/dist/commands/flow.js

@@ -4,7 +4,7 @@ import { resolve } from 'node:path';
 import { FlowManager, isFlowConcurrentError, normalizeAgentName, detectFillState, MODE_DERIVED_TIER, listStageBlockingOpenReviews, PHASE_PATH_MAX_DEPTH } from '../core/flow-manager.js';
 import { PipelinePhaseSchema, PIPELINE_PHASES, REVIEW_TIERS, TIER_PRUNED_PHASES, DEFAULT_EFFECTIVE_REVIEW_TIER } from '../core/pipeline-schema.js';
 import { validateStageId, suggestStageId, normalizeStageId, findStageStatusPath, isArchivedVersionOf } from '../core/plan/path.js';
-import { getConfigFieldLegalValues, setConfigValue } from '../core/config.js';
+import { getConfigFieldLegalValues, setConfigValue, readExplicitConfigDefaults } from '../core/config.js';
 import { parse as parseYaml } from 'yaml';
 import { MetricsStore, PHASE_AGENT_MAP } from '../core/metrics.js';
 import { runtimeLog } from '../core/runtime-log.js';
@@ -160,9 +160,19 @@ export function registerFlowCommand(program) {
         const rawStage = data.pipeline.current.stage || '';
         // 双键回退（与 core resolveCurrentPhase / advanceStagePhase 同范式）：归一化键优先，其次原始键
         const normalized = rawStage ? (normalizeStageId(rawStage) ?? rawStage) : '';
-        const activeKey = rawStage
+        let activeKey = rawStage
             ? (data.stages[normalized] ? normalized : (data.stages[rawStage] ? rawStage : null))
             : null;
+        let derivedFromStages = false;
+        // v1.3.3 P1-1：current 为空时从 stages **只读派生**活跃阶段（tie-break：插入序首个非 done）。
+        // 不写盘、不改 current；命中时在 guards 末位追加派生提示。
+        if (!activeKey) {
+            const derived = Object.entries(data.stages).find(([, stage]) => stage.phase !== 'done');
+            if (derived) {
+                activeKey = derived[0];
+                derivedFromStages = true;
+            }
+        }
         let phase = null;
         let phaseLabel = null;
         let responsibleAgent = 'feel'; // 无活跃阶段显式约定
@@ -188,8 +198,9 @@ export function registerFlowCommand(program) {
             blockingReviews = listStageBlockingOpenReviews(data.reviews, activeKey).map((r) => ({
                 id: r.id, title: r.title, priority: r.priority, op: r.op,
             }));
-            // 守卫顺序契约固定（§12.1）：auto-advance → blocking → 无目标 → 档位差
-            if (mgr.resolveEffectiveConfig()['auto_advance']?.value === 'disabled') {
+            // 守卫顺序契约固定（§12.1）：auto-advance → blocking → 无目标 → 档位差 → 配置组合 → 派生
+            const effectiveCfg = mgr.resolveEffectiveConfig();
+            if (effectiveCfg['auto_advance']?.value === 'disabled') {
                 guards.push(t('flow.next.guardAutoAdvanceDisabled', lang));
             }
             if (blockingReviews.length > 0) {
@@ -201,6 +212,18 @@ export function registerFlowCommand(program) {
             if (reviewTier !== effectiveReviewTier) {
                 guards.push(t('flow.next.guardTierDiffTmpl', lang, { display: reviewTier, effective: effectiveReviewTier }));
             }
+            // P1-4：execution_mode × auto_advance **显式**组合不一致 → 显式提示。
+            // 仅告警「auto 但关闭自动推进」这一**静默无效**组合；manual+enabled 是内置默认（裁定 E），不告警。
+            const explicitCfg = readExplicitConfigDefaults(process.cwd());
+            if (explicitCfg.execution_mode === 'auto' && explicitCfg.auto_advance === 'disabled') {
+                guards.push(t('flow.next.guardConfigComboTmpl', lang, {
+                    mode: explicitCfg.execution_mode,
+                    auto: explicitCfg.auto_advance,
+                }));
+            }
+            if (derivedFromStages) {
+                guards.push(t('flow.next.guardDerivedStage', lang));
+            }
         }
         else {
             guards.push(t('flow.next.guardNoActiveStage', lang));
@@ -840,6 +863,7 @@ export function registerFlowCommand(program) {
         .option('--force', '强制执行（跳过非法 phase 校验和阶段跳跃检查，但不可绕过 REV 阻塞检查）')
         .option('--dry-run', '仅验证不执行修改（预览输出）。与 --force 组合时跳过校验但仍不执行修改')
         .option('--review-tier <tier>', '审查档位（full / lean / skip；缺省=full（零裁剪）；仅显式声明时裁剪审查关，不可绕过 REV 阻塞检查）')
+        .option('--reason <text>', '返工原因（仅 review_passed → exec_running 时写入审计日志 rework_reason）')
         .option('--json', '以 JSON 输出错误封装（仅失败时；成功输出保持人类文本）')
         .option('--quiet', '静默非错误输出（成功确认与 Git 警告均不打印）')
         .action((options) => {
@@ -885,6 +909,17 @@ export function registerFlowCommand(program) {
         }
         // REV-005：命令层归一化（短名 → 全名），与 plan.ts / flow.ts 其它 stage 解析点同范式
         const stageArg = normalizeStageId(options.stage) ?? options.stage;
+        // P1-4：双开关**显式**组合不一致 → 显式告警（仅「auto + auto_advance=disabled」这一静默无效组合；
+        // builtin / 模板默认 manual+enabled 不告警，避免每个新项目首推即噪声）
+        if (!options.quiet) {
+            const explicitCfg = readExplicitConfigDefaults(process.cwd());
+            if (explicitCfg.execution_mode === 'auto' && explicitCfg.auto_advance === 'disabled') {
+                info(t('flow.advance.configComboWarnTmpl', lang, {
+                    mode: explicitCfg.execution_mode,
+                    auto: explicitCfg.auto_advance,
+                }));
+            }
+        }
         // 自动修复 phase/status 不一致（在 validate() 前执行）
         if (options.stage) {
             // B1 修复：dry-run 走预览模式（不写内存/不写盘），仅在非 dry-run 时 save()
@@ -1068,11 +1103,26 @@ export function registerFlowCommand(program) {
         let prevStepDoneMs = 0; // 多步时上一步完成时刻（i>0 的窗口基线）
         const totalSteps = phasePath.length;
         let archivedAny = false;
+        let reasonUsed = false;
         for (let i = 0; i < totalSteps; i++) {
             const next = phasePath[i];
             let archived = false;
             try {
-                archived = mgr.advanceStagePhase(stageArg, next, 'cli', explicitTier ? { reviewTier: explicitTier } : undefined);
+                // 返工原因仅写入「review_passed → exec_running」这一步（P0-3）
+                const fromPhaseStep = i > 0 ? phasePath[i - 1] : startPhase;
+                const reworkReason = options.reason !== undefined
+                    && fromPhaseStep === 'review_passed'
+                    && next === 'exec_running'
+                    ? options.reason
+                    : undefined;
+                if (reworkReason !== undefined)
+                    reasonUsed = true;
+                const stepOpts = {};
+                if (explicitTier)
+                    stepOpts.reviewTier = explicitTier;
+                if (reworkReason !== undefined)
+                    stepOpts.reworkReason = reworkReason;
+                archived = mgr.advanceStagePhase(stageArg, next, 'cli', Object.keys(stepOpts).length > 0 ? stepOpts : undefined);
             }
             catch (err) {
                 const stderrLines = [];
@@ -1149,6 +1199,16 @@ export function registerFlowCommand(program) {
         // 成功确认（单步与多步统一）；--quiet 完全静默
         if (!options.quiet) {
             console.log(t('flow.advance.okTmpl', lang, { stage: stageArg, to: options.to }));
+            // P1-5：显式回显本次生效档位（展示档位 ≠ 生效档位时不再静默）
+            console.log(t('flow.advance.reviewTierTmpl', lang, {
+                tier: effTier,
+                source: explicitTier
+                    ? t('flow.advance.reviewTierSourceExplicit', lang)
+                    : t('flow.advance.reviewTierSourceDefault', lang),
+            }));
+            if (options.reason !== undefined && !reasonUsed) {
+                console.warn(t('flow.advance.reasonIgnoredTmpl', lang));
+            }
         }
         // git 脏区检查（安全网）：默认仅 --to done 时提示；--quiet / 非 done → 完全跳过（含跳过 git 子进程）
         if (!options.quiet && (options.to === 'done' || archivedAny)) {
@@ -1349,23 +1409,38 @@ export function registerFlowCommand(program) {
     const reviewCmd = flow
         .command('review')
         .description('管理审查条目');
-    // flow review add --op <id> [--title] [--auto-fix <detail>]
+    // flow review add [--op <id> | --stage <id>] [--title] [--auto-fix <detail>]
     reviewCmd
         .command('add')
-        .description('添加审查条目')
-        .requiredOption('--op <id>', '操作 ID（如 stage-01.op-001）')
+        .description('添加审查条目（op 级或阶段级；fast 无 op 时用 --stage）')
+        .option('--op <id>', '操作 ID（如 stage-01.op-001）；与 --stage 二选一')
+        .option('--stage <id>', '阶段 ID（未提供 --op 时挂阶段级 REV；与 --op 二选一）')
         .option('--title <title>', '审查标题')
-        .option('--auto-fix <detail>', '自动修复说明，设置后跳过 scheme_pending 直接推进到 exec_running')
+        .option('--auto-fix <detail>', '自动修复说明，设置后跳过 scheme_pending 直接推进到 exec_running（必须配 --op）')
         .option('--blocking [boolean]', '是否阻塞流水线（默认 true）', 'true')
         .action((options) => {
         const lang = getCliLang(process.cwd());
+        // 目标二选一校验（P0-2：fast 无 op 时允许挂 stage）
+        if (!options.op && !options.stage) {
+            const message = t('flow.review.errorNoTarget', lang);
+            console.error(message);
+            process.exit(1);
+            return;
+        }
+        if (options.autoFix && !options.op) {
+            const message = t('flow.review.errorAutoFixNeedsOp', lang);
+            console.error(message);
+            process.exit(1);
+            return;
+        }
         // 单点实现：解析 / 校验 / REV ID 分配 / 写入均由 addReviewEntry 统一处理（T37/R4）
         const blocking = options.blocking !== undefined
             ? !(options.blocking === 'false' || options.blocking === false)
             : true;
         const result = addReviewEntry(process.cwd(), {
             opId: options.op,
-            title: options.title || t('flow.review.detail', lang) + `: ${options.op}`,
+            stageId: options.stage,
+            title: options.title || t('flow.review.detail', lang) + `: ${options.op ?? options.stage}`,
             priority: 'medium',
             autoFixDetail: options.autoFix,
             blocking,
@@ -1376,6 +1451,15 @@ export function registerFlowCommand(program) {
                 case 'notLoaded':
                     console.error(t('common.errorNoInit', lang));
                     break;
+                case 'invalidPriority':
+                    console.error(t('flow.review.errorInvalidPriorityTmpl', lang, { priority: result.error.priority }));
+                    break;
+                case 'invalidTarget':
+                    console.error(t('flow.review.errorNoTarget', lang));
+                    break;
+                case 'autoFixRequiresOp':
+                    console.error(t('flow.review.errorAutoFixNeedsOp', lang));
+                    break;
                 case 'invalidOpId':
                     console.error(t('common.invalidOpId', lang));
                     break;
@@ -1385,9 +1469,6 @@ export function registerFlowCommand(program) {
                 case 'opNotFound':
                     console.error(t('flow.review.errorOpNotFoundTmpl', lang, { opId: result.error.opId, op: result.error.op, stage: result.error.stage }));
                     break;
-                case 'invalidPriority':
-                    console.error(t('flow.review.errorInvalidPriorityTmpl', lang, { priority: result.error.priority }));
-                    break;
             }
             process.exit(1);
             return;
@@ -1400,9 +1481,12 @@ export function registerFlowCommand(program) {
             console.log(`  ` + t('flow.review.detail', lang) + `: ${options.autoFix}`);
             console.log(t('flow.review.autoFixPhase', lang));
         }
-        else {
+        else if (options.op) {
             console.log(t('flow.review.addedTmpl', lang, { label: blockingLabel, revId: review.id, op: options.op }) + (options.title ? ` — ${options.title}` : ''));
         }
+        else {
+            console.log(t('flow.review.addedStageTmpl', lang, { label: blockingLabel, revId: review.id, stage: options.stage }) + (options.title ? ` — ${options.title}` : ''));
+        }
     });
     // flow review resolve <rev-id>
     reviewCmd