@twinsearth/dsh-master 3.3.3 → 3.3.4

package/dist-host/plugins/dual-manager.js

@@ -2,31 +2,32 @@
 // Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
 // @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
 /**
- * 子插件 3：双主管（PM + PJM）。
+ * 双智能体共享服务（PM + PJM）。
  *
- * 定位：运行在母体/元主内的元 Agent；PM 把模糊需求变成结构化 PRD，PJM 把 PRD
- * 拆成步骤并通过瓮城的 fangForker 调度分身执行。本子插件不直接运行生产任务：
- *   * 没有 fangForker.spawn 时 dispatch fail-closed；
- *   * 歧义澄清复用瓮城决策中心（fangDecisionCenter），不另造一套审批；
- *   * 角色：只允许 mother / essence（分身里没有“管理层”）。
+ * `master-pm` / `master-pjm` 是两个独立的 DSH Agent preset；本服务保存它们协作的
+ * 结构化 PRD、六类盘点、WBS、节点与结案状态，并负责文档落盘。
+ *
+ * 边界：
+ *   * PM 只做需求与证据盘点，不执行代码、不派发分身；
+ *   * PJM 只做计划、隔离派发、进度与结案，不替用户决定需求；
+ *   * 没有 fangForker.spawn 时 dispatch fail-closed，绝不在宿主本地降级执行；
+ *   * 歧义澄清复用瓮城决策中心，不另造一套审批；
+ *   * 文档只写当前 Session workspace 下的 docs/pm 或 docs/pjm，不接受任意路径。
  */
-import { FANG_SERVICE, ROW, SERVICE, createIdFactory, detectRole, enabledOf, masterError, roleAllowed, safeGet, } from "../kernel.js";
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { FANG_SERVICE, MASTER_VERSION, ROW, SERVICE, createIdFactory, detectRole, enabledOf, masterError, roleAllowed, safeGet, } from "../kernel.js";
+import { closePlan, normalizeAssessment, normalizePlan, normalizePrd, planProgress } from "../dual/schema.js";
+import { renderAssessmentDocument, renderClosureDocument, renderPrdDocument, renderProjectDocument } from "../dual/documents.js";
 export const name = 'dsh-master-dual-manager';
 export const inject = ['dshMaster'];
 export const ROW_ID = ROW.dual;
-const PRIORITIES = Object.freeze(['low', 'normal', 'high', 'critical']);
-const DEFAULT_STEP_KIND = 'development';
-function stringList(value) {
-    if (!Array.isArray(value))
-        return [];
-    return value.map((item) => String(item ?? '').trim()).filter(Boolean);
-}
 function missing(name) {
     return masterError(`${name}-required`, `${name} is required`);
 }
 /**
  * @param {object} ctx
- * @param {{enabled?:boolean}} [config]
+ * @param {{enabled?:boolean, dispatch?:object}} [config]
  */
 export function apply(ctx, config = {}) {
     if (!enabledOf(config))
@@ -34,7 +35,7 @@ export function apply(ctx, config = {}) {
     const role = detectRole();
     if (!roleAllowed(ROW_ID, role)) {
         try {
-            ctx?.logger?.info?.(`[dsh-master] dual-manager skipped: role=${role} not in mother/essence`);
+            ctx?.logger?.info?.(`[dsh-master] dual-manager skipped: role=${role}`);
         }
         catch { /* ignore */ }
         return { skipped: true, reason: `role-not-allowed:${role}` };
@@ -44,37 +45,48 @@ export function apply(ctx, config = {}) {
         return { skipped: true, reason: 'master-core-unavailable' };
     }
     const newPrdId = createIdFactory('prd');
+    const newAssessmentId = createIdFactory('review');
     const newPlanId = createIdFactory('plan');
     const prds = new Map();
+    const assessments = new Map();
     const plans = new Map();
     const decisionCenter = () => safeGet(ctx, FANG_SERVICE.decisionCenter);
     const forker = () => {
         const service = safeGet(ctx, FANG_SERVICE.forker);
         return service && typeof service.spawn === 'function' ? service : null;
     };
+    /** 文档写口：只接受代码内生成的相对路径，根目录来自当前 Session。 */
+    async function writeWorkspaceDocument(agent, relativePath, content) {
+        const workingDirectory = safeGet(ctx, 'workingDirectory');
+        if (!workingDirectory)
+            return masterError('working-directory-unavailable', 'workingDirectory service is required to write agent documents');
+        try {
+            const root = agent && typeof workingDirectory.ensure === 'function'
+                ? await workingDirectory.ensure(agent)
+                : String(workingDirectory.defaultDirectory ?? '');
+            if (!root)
+                return masterError('working-directory-unavailable', 'no active Session workspace');
+            const base = path.resolve(String(root));
+            const target = path.resolve(base, relativePath);
+            if (target !== base && !target.startsWith(`${base}${path.sep}`)) {
+                return masterError('document-path-outside-workspace', 'document path must stay inside the Session workspace');
+            }
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.writeFile(target, String(content), 'utf8');
+            return { ok: true, path: target, bytes: Buffer.byteLength(String(content), 'utf8') };
+        }
+        catch (error) {
+            return masterError('document-write-failed', String(error?.message ?? error));
+        }
+    }
     const pm = {
-        /** 需求 → 结构化 PRD（不调用模型；3.2.x 接入 PM agent 后由模型填充字段）。 */
+        /** 需求 → 结构化 PRD（模型通过 pm-agent 工具填充；服务本身不调用模型）。 */
         createPrd(input = {}) {
-            const title = String(input.title ?? '').trim();
-            const goal = String(input.goal ?? '').trim();
-            if (!title)
-                return missing('title');
-            if (!goal)
-                return missing('goal');
-            const priority = PRIORITIES.includes(String(input.priority ?? 'normal')) ? String(input.priority ?? 'normal') : 'normal';
-            const prd = Object.freeze({
-                id: newPrdId(),
-                title,
-                goal,
-                priority,
-                constraints: Object.freeze(stringList(input.constraints)),
-                acceptance: Object.freeze(stringList(input.acceptance)),
-                requester: String(input.requester ?? 'user'),
-                status: 'draft',
-                createdAt: Date.now(),
-            });
-            prds.set(prd.id, prd);
-            return { ok: true, prd };
+            const made = normalizePrd(input, { id: newPrdId() });
+            if (!made.ok)
+                return made;
+            prds.set(made.prd.id, made.prd);
+            return made;
         },
         getPrd(id) {
             const prd = prds.get(String(id ?? ''));
@@ -83,6 +95,45 @@ export function apply(ctx, config = {}) {
         listPrds() {
             return { ok: true, items: [...prds.values()] };
         },
+        /** 六类现状盘点；completed 必须由调用方给出可复核证据。 */
+        createAssessment(input = {}) {
+            const prdId = String(input.prdId ?? '').trim();
+            if (prdId && !prds.has(prdId))
+                return masterError('prd-not-found', 'PRD not found', { id: prdId });
+            const made = normalizeAssessment(input, { id: newAssessmentId() });
+            if (!made.ok)
+                return made;
+            assessments.set(made.assessment.id, made.assessment);
+            return made;
+        },
+        getAssessment(id) {
+            const assessment = assessments.get(String(id ?? ''));
+            return assessment ? { ok: true, assessment } : masterError('assessment-not-found', 'Assessment not found', { id: String(id ?? '') });
+        },
+        listAssessments() {
+            return { ok: true, items: [...assessments.values()] };
+        },
+        renderPrd(id, { assessmentId = '' } = {}) {
+            const prd = prds.get(String(id ?? ''));
+            if (!prd)
+                return masterError('prd-not-found', 'PRD not found', { id: String(id ?? '') });
+            const assessment = assessmentId ? assessments.get(String(assessmentId)) : null;
+            if (assessmentId && !assessment)
+                return masterError('assessment-not-found', 'Assessment not found', { id: String(assessmentId) });
+            return { ok: true, markdown: renderPrdDocument(prd, assessment) };
+        },
+        async writePrd(id, { assessmentId = '', agent } = {}) {
+            const rendered = pm.renderPrd(id, { assessmentId });
+            if (!rendered.ok)
+                return rendered;
+            return await writeWorkspaceDocument(agent, path.join('docs', 'pm', `PRD-${id}.md`), rendered.markdown);
+        },
+        async writeAssessment(id, { agent } = {}) {
+            const assessment = assessments.get(String(id ?? ''));
+            if (!assessment)
+                return masterError('assessment-not-found', 'Assessment not found', { id: String(id ?? '') });
+            return await writeWorkspaceDocument(agent, path.join('docs', 'pm', `REVIEW-${id}.md`), renderAssessmentDocument(assessment));
+        },
         /** 歧义澄清：复用瓮城决策中心，返回 ticket 或明确的 unavailable。 */
         async askUser({ question, context = '', options = [], level = 'yellow' } = {}) {
             const q = String(question ?? '').trim();
@@ -110,61 +161,46 @@ export function apply(ctx, config = {}) {
         },
     };
     const pjm = {
-        /** PRD → 可调度步骤计划。 */
-        plan(prdId, { steps = [] } = {}) {
+        /** PRD → 七类项目计划与可调度 WBS。 */
+        plan(prdId, input = {}) {
             const prd = prds.get(String(prdId ?? ''));
             if (!prd)
                 return masterError('prd-not-found', 'PRD not found', { id: String(prdId ?? '') });
-            if (!Array.isArray(steps) || steps.length === 0)
-                return missing('steps');
-            const normalized = [];
-            for (const [index, step] of steps.entries()) {
-                const title = String(step?.title ?? '').trim();
-                const prompt = String(step?.prompt ?? '').trim();
-                if (!title)
-                    return missing(`steps[${index}].title`);
-                if (!prompt)
-                    return missing(`steps[${index}].prompt`);
-                normalized.push({
-                    id: String(step?.id ?? `step-${index + 1}`),
-                    title,
-                    prompt,
-                    kind: String(step?.kind ?? DEFAULT_STEP_KIND),
-                    status: 'pending',
-                    fork: null,
-                });
-            }
-            const plan = {
-                id: newPlanId(),
-                prdId: prd.id,
-                status: 'planned',
-                steps: normalized,
-                createdAt: Date.now(),
-            };
-            plans.set(plan.id, plan);
-            return { ok: true, plan };
+            const made = normalizePlan(prd, input, { id: newPlanId() });
+            if (!made.ok)
+                return made;
+            plans.set(made.plan.id, made.plan);
+            return made;
         },
         getPlan(id) {
             const plan = plans.get(String(id ?? ''));
             return plan ? { ok: true, plan } : masterError('plan-not-found', 'Plan not found', { id: String(id ?? '') });
         },
+        progress(id) {
+            const plan = plans.get(String(id ?? ''));
+            if (!plan)
+                return masterError('plan-not-found', 'Plan not found', { id: String(id ?? '') });
+            return { ok: true, planId: plan.id, status: plan.status, progress: planProgress(plan), steps: plan.steps };
+        },
         /** 调瓮城 fangForker.spawn 派生执行分身；无 forker 时 fail-closed。 */
         async dispatch(planId, { stepId } = {}) {
             const plan = plans.get(String(planId ?? ''));
             if (!plan)
                 return masterError('plan-not-found', 'Plan not found', { id: String(planId ?? '') });
+            if (plan.status === 'closed')
+                return masterError('plan-already-closed', 'Closed plans cannot dispatch new steps');
             const step = plan.steps.find((item) => item.id === String(stepId ?? ''));
             if (!step)
                 return masterError('step-not-found', 'Step not found', { id: String(stepId ?? '') });
             if (step.fork)
                 return masterError('step-already-dispatched', 'Step already dispatched', { stepId: step.id, fork: step.fork });
             const fangForker = forker();
-            if (!fangForker) {
+            if (!fangForker)
                 return masterError('fang-forker-unavailable', 'dsh-fang fangForker.spawn is required to dispatch a step');
-            }
             // 先占位再 await，避免两个并发 dispatch 同时看到 step.fork=null 而重复派生。
             step.status = 'dispatching';
             step.fork = { pending: true };
+            plan.updatedAt = Date.now();
             try {
                 const spawnConfig = config.dispatch && typeof config.dispatch === 'object' ? config.dispatch : {};
                 const fork = await fangForker.spawn({
@@ -188,6 +224,7 @@ export function apply(ctx, config = {}) {
                 step.status = 'running';
                 step.fork = fork ?? null;
                 plan.status = 'running';
+                plan.updatedAt = Date.now();
                 return { ok: true, planId: plan.id, stepId: step.id, step, fork };
             }
             catch (error) {
@@ -196,40 +233,76 @@ export function apply(ctx, config = {}) {
                 return masterError('fang-spawn-threw', String(error?.message ?? error));
             }
         },
-        completeStep(planId, stepId, { status = 'done', summary = '' } = {}) {
+        completeStep(planId, stepId, { status = 'done', summary = '', evidence = [], actualMinutes = null } = {}) {
             const plan = plans.get(String(planId ?? ''));
             if (!plan)
                 return masterError('plan-not-found', 'Plan not found', { id: String(planId ?? '') });
+            if (plan.status === 'closed')
+                return masterError('plan-already-closed', 'Closed plans cannot be modified');
             const step = plan.steps.find((item) => item.id === String(stepId ?? ''));
             if (!step)
                 return masterError('step-not-found', 'Step not found', { id: String(stepId ?? '') });
-            const next = status === 'failed' ? 'failed' : 'done';
-            step.status = next;
+            step.status = status === 'failed' ? 'failed' : 'done';
             step.summary = String(summary);
+            step.evidence = Array.isArray(evidence) ? evidence.map(String).filter(Boolean) : [];
+            const minutes = Number(actualMinutes);
+            step.actualMinutes = Number.isFinite(minutes) && minutes >= 0 ? minutes : null;
             const states = plan.steps.map((item) => item.status);
             plan.status = states.every((state) => state === 'done')
                 ? 'done'
-                : (states.some((state) => state === 'running') ? 'running' : 'planned');
+                : (states.some((state) => state === 'running' || state === 'dispatching') ? 'running' : 'planned');
+            plan.updatedAt = Date.now();
             return { ok: true, plan };
         },
+        close(planId, input = {}) {
+            const plan = plans.get(String(planId ?? ''));
+            if (!plan)
+                return masterError('plan-not-found', 'Plan not found', { id: String(planId ?? '') });
+            if (plan.status === 'closed')
+                return masterError('plan-already-closed', 'Plan is already closed');
+            return closePlan(plan, input);
+        },
+        renderProject(planId) {
+            const plan = plans.get(String(planId ?? ''));
+            if (!plan)
+                return masterError('plan-not-found', 'Plan not found', { id: String(planId ?? '') });
+            return { ok: true, markdown: renderProjectDocument(plan) };
+        },
+        async writeProject(planId, { agent } = {}) {
+            const rendered = pjm.renderProject(planId);
+            if (!rendered.ok)
+                return rendered;
+            return await writeWorkspaceDocument(agent, path.join('docs', 'pjm', `PROJECT-${planId}.md`), rendered.markdown);
+        },
+        async writeClosure(planId, { agent } = {}) {
+            const plan = plans.get(String(planId ?? ''));
+            if (!plan)
+                return masterError('plan-not-found', 'Plan not found', { id: String(planId ?? '') });
+            if (plan.closure.status !== 'closed')
+                return masterError('plan-not-closed', 'Project must be closed before writing its closure report');
+            const markdown = `# 项目结案 · ${plan.title}\n\n- 计划 ID：\`${plan.id}\`\n- 关联 PRD：\`${plan.prdId}\`\n\n${renderClosureDocument(plan)}\n`;
+            return await writeWorkspaceDocument(agent, path.join('docs', 'pjm', `CLOSURE-${planId}.md`), markdown);
+        },
         listPlans() {
             return { ok: true, items: [...plans.values()] };
         },
     };
     const service = {
         id: SERVICE.dual,
-        version: '3.2.5',
+        version: MASTER_VERSION,
         role,
         pm,
         pjm,
+        agents: Object.freeze({ pm: 'master-pm', pjm: 'master-pjm' }),
         status() {
             return {
                 ok: true,
                 id: 'dual-manager',
-                version: '3.2.5',
+                version: MASTER_VERSION,
                 role,
-                pm: { prds: prds.size },
-                pjm: { plans: plans.size },
+                agents: { pm: 'master-pm', pjm: 'master-pjm' },
+                pm: { prds: prds.size, assessments: assessments.size },
+                pjm: { plans: plans.size, closed: [...plans.values()].filter((plan) => plan.status === 'closed').length },
                 cooperation: {
                     decisionCenter: Boolean(decisionCenter()),
                     forker: Boolean(forker()),
@@ -244,8 +317,8 @@ export function apply(ctx, config = {}) {
     master.registerSubplugin({
         id: 'dual-manager',
         name: 'dsh-master-dual-manager',
-        capabilities: ['pm-prd', 'pm-ask-user', 'pjm-plan', 'pjm-dispatch'],
-        description: 'PM + PJM 双主管（仅 mother/essence）',
+        capabilities: ['pm-prd', 'pm-assessment', 'pm-document', 'pm-ask-user', 'pjm-plan', 'pjm-dispatch', 'pjm-progress', 'pjm-close'],
+        description: 'PM/PJM 双智能体共享服务；master-pm 与 master-pjm preset 复用此服务',
     });
     return service;
 }

package/docs/AGENTS-PM-PJM.md

@@ -0,0 +1,123 @@
+# 房主智能体：PM（产品经理）与 PJM（项目经理）
+
+> 3.3.4 交付。两个**独立的 Agent preset**，可在新建会话时选择；共享 `dual-manager` 服务的结构化状态。
+> 源码：`src/agents/prompts.ts`（角色 Prompt）、`src/agents/pm-agent.ts`、`src/agents/pjm-agent.ts`、
+> `src/dual/schema.ts`（契约与校验）、`src/dual/documents.ts`（文档渲染）。
+
+## 1. 它们是什么 / 不是什么
+
+| | 是 | 不是 |
+|---|---|---|
+| PM | 一个可选择的 Agent preset；只读代码与文档、向用户出选择题、产出 PRD 与六类盘点 | 不是 UI 装饰卡片；不执行代码、不派发分身、不发布 |
+| PJM | 一个可选择的 Agent preset；拆 WBS、经 `fangForker.spawn` 隔离派发、汇总节点、结案 | 不替用户决定需求；没有 forker 时不会本地降级执行 |
+
+两者都**不授予额外权限**：preset 决定“这个会话是谁”，`ROLE_MATRIX` 决定“子插件在哪个角色装配”，
+智能体工具边界写在 `cordis.patch.yml` 的 preset 行里（只读 fs + 提问/待办/交付工具，无 shell、无写文件）。
+
+## 2. PM · 产品经理
+
+**WHY**：把用户和开发者的口语需求变成可核对、可验收的文档，先消除歧义再动手，避免“做完了才发现理解错”。
+**WHAT**：结构化 PRD（WHY/WHAT/模块/约束/非目标/验收）+ 证据驱动的六类现状盘点 + 文档落盘。
+
+角色 Prompt（完整版见 `src/agents/prompts.ts`，摘要）：
+
+```text
+Role   房主产品经理（PM, preset: master-pm）
+Goals  WHY：解决什么问题/达成什么目标；WHAT：功能、模块、架构、结果
+Flow   先澄清（ask_user_question，一次一个决策点，2–4 选项带推荐）
+       → 用 read/grep/glob 读真实代码与测试
+       → pm_create_prd / pm_create_assessment 落结构
+       → pm_write_prd 写 Markdown → present 交付
+Rules  不臆测、不伪造证据、不把“能实现”写成“已完成”；
+       冲突必须列双方/影响/选项；歧义必须写当前理解并等确认；
+       PM 不写生产代码、不跑 shell、不发布、不安装、不调度分身
+```
+
+**六类盘点（PM 的输出契约）**
+
+| 类别 | 必填 | 门禁 |
+|---|---|---|
+| completed | `evidence[]`（文件/测试/报告） | **没有证据直接拒收**，不允许自称 100% |
+| unfinished | `reason`、`nextStep`、`progress` | `progress` 上限 99，不能写成完成 |
+| blocked | `reason`、`blocker`、`nextStep` | 卡点必须具名，不写“暂不可行” |
+| planned | `plan`、`estimateMinutes`、`priority` | 估时以分钟给出 |
+| conflicts | `question`、`options[{value,label,consequence}]` | 必须给出可重新判断的选项 |
+| ambiguities | `question`、`currentInterpretation` | 默认 `needsConfirmation: true` |
+
+**工具**：`pm_create_prd`、`pm_create_assessment`、`pm_write_prd`、`pm_list_prds`（外加 preset 挂载的只读 fs、搜索、`ask_user_question`、`present`）。
+
+## 3. PJM · 项目经理
+
+**HOW**：PRD → WBS（每步 prompt/owner/场景/估时/依赖/验收）。
+**WHO**：每步必须有 owner，未分配写 `unassigned`，不虚构人员。
+**WHERE**：明确执行场景（宿主 / fork / workspace / DSH Web）；脏任务只进隔离执行体。
+**WHEN**：里程碑 + 估时（计划，不是承诺工期）。
+
+角色 Prompt（摘要）：
+
+```text
+Role   房主项目经理（PJM, preset: master-pjm）
+Goals  HOW / WHO / WHERE / WHEN
+Flow   项目会审 → pjm_create_plan（七类内容）
+       → pjm_dispatch_step（仅经 fangForker.spawn，无则 fail-closed）
+       → pjm_complete_step（status/summary/evidence/actualMinutes）
+       → pjm_project_status → pjm_write_project → pjm_close_project
+Rules  真实状态汇报，失败/阻塞/未测量不得包装成完成；
+       不发布、不部署、不改 profile、不碰凭据；
+       不代替 PM 决定需求，不替用户回答选择题
+```
+
+**七类项目管理（PJM 的输出契约）**：项目会审、项目计划（WBS）、项目需求与内容、项目时间、项目人员、测试/部署/交付/验收、项目结案。
+
+**结案门禁**：全部步骤 `done` 才允许结案；结案必须给 `summary`；结案后计划冻结（不能再派发/改步骤）。
+结案文档包含评审报告、验收记录、资料清单。
+
+**工具**：`pjm_create_plan`、`pjm_dispatch_step`、`pjm_complete_step`、`pjm_project_status`、`pjm_write_project`、`pjm_close_project`（外加只读 fs、搜索、`todo_write`、`present`）。
+
+## 4. 协作流水线
+
+```text
+用户口语需求
+   │  (新会话选 preset: master-pm)
+   ▼
+PM: 澄清选择题 → PRD(prd_*) → 六类盘点(review_*) → docs/pm/*.md
+   │  只移交 prdId + 验收标准 + 未决问题
+   ▼
+PJM: 会审 → WBS(plan_*) → fangForker.spawn 派生分身 → 节点汇总
+   │                                      │
+   │                          每步记录 evidence / actualMinutes
+   ▼
+PJM: 全绿 → 结案（summary/评审报告/验收/资料）→ docs/pjm/*.md
+```
+
+当前实现里两者**不共享隐式上下文**：PM 只写 PRD/盘点，PJM 只读 PRD 与自己的计划，跨角色只传 id 与结构。
+
+## 5. 如何启用
+
+1. bundle 已声明两个 preset 行（`cordis.patch.yml`：`preset-master-pm` / `preset-master-pjm`）；
+2. 新会话创建时在 Agent preset 选择器里选「产品经理（PM）」或「项目经理（PJM）」；
+3. 面板「房主」抽屉会多出两张智能体卡片 + 一张**智囊团 Command Center** 只读摘要
+   （PRD / 盘点 / 计划 / 已结案 / 决策中心 / 派发可用性），数据来自 `/dsh-master/api/status` 的 `dual` 段；
+4. 没有 `agentPresets` 服务的宿主（非 DSH web bundle）会显示「本宿主不可用」，不会假装可以选择。
+
+面板**只读**：PRD、盘点、计划、结案只能由 PM/PJM 会话里的工具创建；面板不提供写入口，也不直接调工具。
+
+## 6. 已知限制（不隐藏）
+
+- **未做宿主级验证**：本会话守则 §二 禁止把插件装进任何 profile，因此 preset 只做了源码/契约/工具注册测试，尚未在真实 Host 里点选验证；面板卡片的 `可选择` 也只反映 `agentPresets` 服务是否存在。
+- **没有 VM 工具面**：当前 Host 与本仓库都没有 `vm_create/vm_exec` 那套 27 工具；PJM 的隔离派发走既有 `fangForker.spawn`。若要接 vm-sandbox，需要单独授权并新增适配层。
+- **文档只写 workspace**：`docs/pm`、`docs/pjm` 之外拒绝写入；不提供任意路径写口。
+- **PM 不能改代码、PJM 不能改需求**：这是刻意的边界，不是功能缺失。
+
+## 7. 测试覆盖
+
+`test/dual-agents.test.mjs`（10 条）：
+
+- PRD 校验；completed 无证据拒收；六类字段齐全；
+- PRD/盘点/计划/结案的服务层门禁与冻结；
+- 派发 fail-closed 与真实 fork 记录；
+- 两个 preset 的 persona 与工具清单（PM 4 个、PJM 6 个，且无 shell/写文件）；
+- 端到端工具调用；文档只写 workspace。
+
+另有 `test/kernel.test.mjs`（AGENT_CATALOG 边界）、`test/core.test.mjs`（status 分开报告 agents）、
+`test/package-contract.test.mjs`（preset 行、exports、工具边界静态断言）。

package/docs/ARCHITECTURE.md

@@ -134,5 +134,7 @@ master-cost-optimizer（行，fork/mother）= 编排器 + 服务 dshMasterCost
 - A1 默认 **shadow**：计算「本可节省」但返回原文；只有 `enforce` 且紧凑结果更短才替换，且归因单独入账（不重复计消耗）。
 - 瓮城回流（3.3.1 起）：`src/cost/fang-relay.ts` 走 `@twinsearth/dsh-fang-contract` 1.1.x 的
   `fang.relay.publish` / `fang.relay.status`；只有对端回执才算送达，不可用给具名原因。
+- 智能体（3.3.4）：`master-pm` / `master-pjm` 两个 Agent preset，共享 `dual-manager` 的结构化状态；
+  preset 决定“会话是谁”，角色矩阵决定“子插件在哪装配”，两者都不授予额外执行权限（见 `docs/AGENTS-PM-PJM.md`）。
 - 详见 `docs/DESIGN-v3.3.0-cost-optimization.md`（§0 总体架构、§17 实施进度）、
   `docs/EXPERIMENT-M5-real-ab.md`（真实 A/B）、`docs/EXPERIMENT-M5-fang-relay.md`（回流实测）。

package/docs/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 3.3.4（2026-11-14 已发布）
+
+> 三方发布：annotated tag `v3.3.4` + GitHub Release + npm `@twinsearth/dsh-master@3.3.4`。
+> 接口包无变化（仍 `@twinsearth/dsh-fang-contract@1.1.1`）。
+
+**主题：房主新增两个可选择的智能体 —— 产品经理（PM）与项目经理（PJM）。**
+
+- **两个 Agent preset**：`master-pm`、`master-pjm`（`cordis.patch.yml` 的 `preset-master-pm` / `preset-master-pjm` 行），可在新会话创建时选择；已存在的会话不受影响。
+- **角色 Prompt 落进代码**：`src/agents/prompts.ts` 给出 PM 的 WHY/WHAT/六类盘点契约与 PJM 的 HOW/WHO/WHERE/WHEN/七类项目管理契约，均写死边界（PM 不执行、PJM 无 forker 即 fail-closed）。
+- **结构化契约与门禁**：`src/dual/schema.ts` —— PRD 必填 title/goal；**completed 项没有 evidence 直接拒收**（不允许自称 100%）；plan 步骤必须有 title/prompt，估时缺省显式给 30 分钟；**全部步骤 done 才允许结案**，结案必须给 summary，结案后计划冻结。
+- **`dual-manager` 升级为共享服务**：保留原有 `pm/prd`、`pjm/plan/dispatch` 兼容面，新增 `createAssessment`（六类盘点）、`writePrd`/`writeAssessment`/`writeProject`/`writeClosure`（只写 Session workspace 下的 `docs/pm`、`docs/pjm`）、`progress`（进度按步骤实测）、`close`（结案）。
+- **两个智能体插件**：`src/agents/pm-agent.ts`（4 个工具）、`src/agents/pjm-agent.ts`（6 个工具），通过 `ctx.systemPrompt.section` 挂 persona、`ctx.tools.register` 挂 scoped tools；缺少 `systemPrompt`/`tools`/`diskMasterDual` 时返回具名错误，不静默失败。
+- **面板与状态**：`status().agents` 单独报告两个智能体（与子插件行分开），`status().dual` 给出智囊团只读摘要（PRD/盘点/计划/已结案/协作可用性；未装配时为 `null`，不造空壳）；面板新增两张智能体卡片与「智囊团 · Command Center」只读卡片，**无写入口**；`AGENT_CATALOG` 写死工具边界。
+- **边界**：两个 preset 都不挂 shell、不授予写文件（文档只经 agent 工具写入 workspace）；PJM 的隔离派发仍只走 `fangForker.spawn`，没有 `vm_create/vm_exec` 适配层。
+- 测试：新增 `test/dual-agents.test.mjs`（10 条），并扩充 kernel/core/package-contract 断言；全量 **459 条**。
+
 ## 3.3.3（2026-11-13 已发布）
 
 > 三方发布：annotated tag `v3.3.3` + GitHub Release + npm `@twinsearth/dsh-master@3.3.3`。