openfeel 1.4.0 → 1.5.2

package/dsh/lib/adapters/dev-status.js

@@ -0,0 +1,40 @@
+/**
+ * dev 状态同步（v1.5.0，适配器侧只读）
+ *
+ * 与 CLI `openfeel dev status` 同源：读 `.openfeel/dev/.sync.json` 判断是否到期；
+ * 只读，不写盘。用于 feel_next / feel_status 暴露 statusSync.due。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** 默认同步间隔（分钟） */
+export const DEFAULT_SYNC_INTERVAL_MINUTES = 30;
+
+/**
+ * 读取状态同步快照（缺失/损坏 → due=true 且 lastSync=null）。
+ * @param {string} projectRoot
+ * @param {number} [now]
+ * @returns {{ due: boolean, lastSync: string|null, intervalMinutes: number }}
+ */
+export function readStatusSync(projectRoot, now = Date.now()) {
+  const file = join(projectRoot, '.openfeel', 'dev', '.sync.json');
+  let lastSync = null;
+  let intervalMinutes = DEFAULT_SYNC_INTERVAL_MINUTES;
+  try {
+    if (existsSync(file)) {
+      const raw = JSON.parse(readFileSync(file, 'utf-8'));
+      if (typeof raw.last_sync === 'string') lastSync = raw.last_sync;
+      if (typeof raw.interval_minutes === 'number' && raw.interval_minutes > 0) {
+        intervalMinutes = raw.interval_minutes;
+      }
+    }
+  } catch {
+    /* 损坏 → 视为到期 */
+  }
+  let due = true;
+  if (lastSync !== null) {
+    const last = Date.parse(lastSync);
+    due = !Number.isFinite(last) || now - last >= intervalMinutes * 60_000;
+  }
+  return { due, lastSync, intervalMinutes };
+}

package/dsh/lib/adapters/workflow-gate.js

@@ -0,0 +1,31 @@
+/**
+ * 流程入口闸（v1.5.2）
+ *
+ * 目的：把「无活跃阶段时不得开始需要落盘/多步调查的任务」从提示词约定
+ * 变成 feel_status / feel_next 的结构化字段，避免模型以「只读调研」为由跳过阶段。
+ *
+ * 纯函数、无 IO；由工具层在读取快照后调用。
+ */
+
+/**
+ * @param {Record<string, any>} snapshot readSnapshot 的结果
+ * @returns {{ required: boolean, reason: string|null, message: string, actions: string[] }}
+ */
+export function computeWorkflowGate(snapshot) {
+  const phase = snapshot?.focus?.phase;
+  const hasActiveStage = phase !== '' && phase !== null && phase !== undefined;
+  if (hasActiveStage) {
+    return { required: false, reason: null, message: '', actions: [] };
+  }
+  return {
+    required: true,
+    reason: 'no-active-stage',
+    message:
+      '当前无活跃阶段：任何会产出仓库文件（含 docs/research/**、方案、计划）或需要多步调查/实现的任务，必须先建立阶段；纯只读问答可例外。',
+    actions: [
+      'feel_req action=add title="<需求>"',
+      'feel_req action=claim id=REQ-NNN',
+      'feel_stage action=add stage=<vX.Y.Z-stage-N> tasks=[...]',
+    ],
+  };
+}

package/dsh/lib/guard.js

@@ -78,6 +78,22 @@ function isDocPath(absolute, cwd) {
     || absolute.startsWith(`${docsRoot}/`);
 }
 
+/**
+ * 是否为研究/方案产物（v1.5.2）：工作区根级 `docs/research/**`。
+ *
+ * 这类文件是**阶段交付物**而非随手笔记：即使 doc 层原本任意相位可写，
+ * 无活跃阶段时也要求先建立阶段，防止以「只读调研」为由跳过流程。
+ * @param {string} absolute 已归一化绝对路径
+ * @param {string} cwd 已归一化工作区
+ * @returns {boolean}
+ */
+function isResearchArtifactPath(absolute, cwd) {
+  const root = normalizeTarget(cwd, 'docs/research');
+  return absolute === root
+    || absolute.startsWith(`${root}\\`)
+    || absolute.startsWith(`${root}/`);
+}
+
 /**
  * 是否位于工作区内（bootstrap 例外边界；防 `..`/绝对路径写出工作区）。
  * @param {string} absolute 已归一化绝对路径
@@ -114,10 +130,10 @@ function isExemptPath(absolute, cwd) {
 }
 
 /**
- * 写入门禁审计（v1.4.0）：豁免放行时追加 JSONL 到 `.openfeel/log/guard-audit.jsonl`。
- * best-effort：任何写失败都吞掉，不影响放行结果。
+ * 写入门禁审计（v1.4.0 / v1.5.2）：放行与拒绝都追加 JSONL 到 `.openfeel/log/guard-audit.jsonl`。
+ * best-effort：任何写失败都吞掉，不影响判定结果。
  * @param {string} cwd 已归一化工作区
- * @param {{ tool: string, reason: 'doc-asset'|'chore', phase: string, paths: string[] }} event
+ * @param {{ event?: 'guard_allow'|'guard_deny', tool: string, reason: string, phase: string, paths: string[] }} event
  */
 function recordGuardAudit(cwd, event) {
   try {
@@ -127,7 +143,7 @@ function recordGuardAudit(cwd, event) {
     }
     const entry = {
       time: new Date().toISOString(),
-      event: 'guard_allow',
+      event: event.event ?? 'guard_allow',
       tool: event.tool,
       reason: event.reason,
       phase: event.phase,
@@ -483,6 +499,21 @@ export function createOpenFeelGuard(options = {}) {
     }
 
     const active = activeStages(flow.value);
+    // v1.5.2 入口闸：研究/方案产物（docs/research/**）是阶段交付物，无活跃阶段时不得写入；
+    // chore 也不能绕过（在下方 chore 放行之前判定）。
+    if (active.length === 0 && targets.some((target) => isResearchArtifactPath(target, normalizedCwd))) {
+      recordGuardAudit(normalizedCwd, {
+        event: 'guard_deny',
+        tool: name,
+        reason: 'research-needs-stage',
+        phase: 'done',
+        paths: targets,
+      });
+      return t(
+        'OpenFeel 写入门禁：研究/方案产物（docs/research/**）要求有活跃阶段。请先 feel_req add → claim → feel_stage add 建立阶段，再写调研/方案。纯只读问答无需落盘。',
+        'OpenFeel write guard: research/proposal artifacts (docs/research/**) require an active stage. Create one via feel_req add → claim → feel_stage add before writing. Pure read-only Q&A needs no file.',
+      );
+    }
     if (active.length === 0) {
       if (allowGeneral && hasGeneralRequirement(flow.value)) return undefined;
       // v1.4.0 chore 通道：仅在**无活跃阶段**时生效；受保护路径已在上方拒绝。

package/dsh/lib/surface/prompt.js

@@ -141,6 +141,16 @@ Feel（你）只做编排、决策与门禁判断。
 - **归档判据不可协商**：版本归档要求该版本**全部阶段 done** 且**无 blocking open REV**，没有 force 覆盖。归档由 CLI 执行，调度侧只提示不代劳。
 - **不主动读归档**：常规调度不要读 \`.openfeel/flow-archive/**\`（防上下文污染）；需要历史时用 \`feel_archive action=show\`。
 
+## 流程入口（v1.5.2）
+- **先 \`feel_status\`**：任何会产出仓库文件（含 \`docs/research/**\`、方案、计划）或需要多步调查/实现的任务，先读状态；无活跃阶段 → \`feel_req add\` → \`claim\` → \`feel_stage add\`，再开始。
+- **不得以「调研 / 只读」为由跳过阶段**：纯只读问答可直接回答；研究/方案产物写入门禁要求活跃阶段（\`docs/research/**\` 无阶段会被拒）。
+- **判据**：只要任务可能改变仓库内容或需要跨轮次承接，就属于流程任务。
+
+## 状态与记录（v1.5.0）
+- **只有 Feel 写状态**：\`dev_last*\`、\`dev/current.md\`、\`status.md\`、\`flow.json\` 只由 Feel 更新；**子 agent 一律不读不写**（上下文由派发 prompt / 交接文档提供）。
+- **日志不强制**：不写流水账；\`flow.json.log\` 由 CLI 自动维护（仅保留最近 200 条）。跨会话信息用一条 ≤5 行交接摘要。
+- **更新节点**：开始 / 转折 / 结束，或 \`statusSync.due=true\`（默认 30 分钟）时更新一次交接摘要，随后运行 \`openfeel dev sync\`（CLI 在节点/到期时也会自动同步）。
+
 ## 三种工作流模式
 - \`full\`：plan → plan_review → scheme → exec → review → test → archive，六道关全走。
 - \`fast\`：跳过 \`scheme_*\` 与 \`test_*\`；**计划审查与代码审查各保留一轮**（fast 不等于免审）。
@@ -196,6 +206,16 @@ planner / schemer / executor / reviewer / feel-tester / archiver. **The authorit
 - **Archive criteria are not negotiable**: a version archive requires every stage of that version to be \`done\` AND no blocking open REV; there is no force override. The CLI performs the archive; you only prompt.
 - **Do not read archives during normal scheduling**: avoid \`.openfeel/flow-archive/**\`; use \`feel_archive action=show\` on demand.
 
+## Workflow entry (v1.5.2)
+- **Call \`feel_status\` first**: any task that may produce repo files (including \`docs/research/**\`, proposals, plans) or needs multi-step investigation/implementation must read state first; with no active stage → \`feel_req add\` → \`claim\` → \`feel_stage add\`, then start.
+- **Never skip the stage under the pretext of "research / read-only"**: pure read-only Q&A may answer directly; research/proposal artifacts require an active stage (\`docs/research/**\` writes are rejected without one).
+- **Rule of thumb**: if it may change repo content or span multiple turns, it is a workflow task.
+
+## State & records (v1.5.0)
+- **Only Feel writes state**: \`dev_last*\`, \`dev/current.md\`, \`status.md\`, \`flow.json\` are updated by Feel only; **subagents never read or write them** (context comes from the dispatch prompt / handoff docs).
+- **No mandatory logs**: do not keep a per-step diary; \`flow.json.log\` is maintained by the CLI (last 200 entries only). For cross-session info, write a <=5-line handoff summary.
+- **Update nodes**: start / turning point / end, or when \`statusSync.due=true\` (default 30 min) — update the handoff summary once, then run \`openfeel dev sync\` (the CLI also auto-syncs on nodes/expiry).
+
 ## The three workflow modes
 - \`full\`: plan → plan_review → scheme → exec → review → test → archive (all six gates).
 - \`fast\`: skips \`scheme_*\` and \`test_*\`; **plan review and code review each keep one round** (fast is not review-free).

package/dsh/lib/tools/index.js

@@ -13,6 +13,8 @@
 
 import { FeelError } from '../adapters/cli.js';
 import { legalNextPhases, planNextStep, readSnapshot } from '../adapters/dashboard.js';
+import { readStatusSync } from '../adapters/dev-status.js';
+import { computeWorkflowGate } from '../adapters/workflow-gate.js';
 import { resolveWorkspace } from '../adapters/workspace.js';
 import {
   boolean,
@@ -152,10 +154,13 @@ export function createTools(context) {
           withRequirements: args.with_requirements === true,
         });
         snapshot.project.root = resolved.cwd;
+        snapshot.statusSync = readStatusSync(resolved.cwd);
+        snapshot.workflowGate = computeWorkflowGate(snapshot);
         const focus = snapshot.focus;
+        const gateWarning = snapshot.workflowGate.required ? '⚠ 无活跃阶段：非只读任务先 feel_status→建阶段。' : '';
         return {
           data: snapshot,
-          summary: `pipeline=${snapshot.pipeline.phase || '(空)'} 活跃阶段=${focus.stage || '(无)'} phase=${focus.phase || '(空)'} mode=${snapshot.mode.current}(${snapshot.mode.source}) 负责=${focus.responsibleAgent} 可推进到=[${(focus.legalNextPhases ?? []).join(', ') || '无'}]`,
+          summary: `${gateWarning}pipeline=${snapshot.pipeline.phase || '(空)'} 活跃阶段=${focus.stage || '(无)'} phase=${focus.phase || '(空)'} mode=${snapshot.mode.current}(${snapshot.mode.source}) 负责=${focus.responsibleAgent} 可推进到=[${(focus.legalNextPhases ?? []).join(', ') || '无'}]`,
           next: focus.phase === 'done' || focus.phase === ''
             ? null
             : { tool: 'feel_next', arguments: {}, why: '获取「下一步该谁做」的明确建议。' },
@@ -182,7 +187,13 @@ export function createTools(context) {
       return envelope('next', async () => {
         const snapshot = await readSnapshot(cli, { cwd: resolved.cwd, signal: exec.signal });
         snapshot.project.root = resolved.cwd;
+        snapshot.statusSync = readStatusSync(resolved.cwd);
+        snapshot.workflowGate = computeWorkflowGate(snapshot);
         const plan = planNextStep(snapshot);
+        plan.workflowGate = snapshot.workflowGate;
+        if (plan.workflowGate.required) {
+          plan.summary = `⚠ ${plan.workflowGate.message} ${plan.summary}`;
+        }
         return {
           data: plan,
           summary: plan.summary,

package/dsh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openfeel-dsh",
-  "version": "1.4.0",
+  "version": "1.5.2",
   "description": "OpenFeel × DSH — Feel 模式适配器：把 OpenFeel 的流水线、需求分发、版本归档与知识库接入 DeepSeek Harness",
   "type": "module",
   "private": true,
@@ -32,7 +32,7 @@
   },
   "openfeel": {
     "adapter": "dsh",
-    "requiresCli": ">=1.4.0"
+    "requiresCli": ">=1.5.2"
   },
   "keywords": [
     "openfeel",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openfeel",
-  "version": "1.4.0",
+  "version": "1.5.2",
   "description": "AI Agent 开发流程治理 CLI 工具",
   "type": "module",
   "private": false,