@xirang-ai/dsh-teamflow 0.1.0 → 0.1.2

package/lib/store/docs.js

@@ -1,23 +1,20 @@
 /**
- * 文档落盘：正文不进 SQLite，只记工作区内的相对路径。
+ * 文档落盘：正文不进 SQLite，只记文档根内的相对路径。
  *
- * 目录结构（相对工作区根）：
+ * 目录结构（相对文档根，默认 `$DSH_HOME/xirang-ai/dsh-teamflow/docs`）：
  *
- *   .xirang-ai/dsh-teamflow/
- *     requirements/<req_id>/requirement.md 需求 + 概要设计正文
- *     requirements/<req_id>/docs/<doc_id>.md 详细设计文档（一份需求可以有很多份）
- *     stories/<sty_id>/story.md            故事说明 + 验收标准
- *     bugs/<bug_id>/bug.md                 缺陷正文（描述、复现、期望、实际、环境）
+ *   requirements/<req_id>/requirement.md 需求 + 概要设计正文
+ *   requirements/<req_id>/docs/<doc_id>.md 详细设计文档（一份需求可以有很多份）
+ *   stories/<sty_id>/story.md            故事说明 + 验收标准
+ *   bugs/<bug_id>/bug.md                 缺陷正文（描述、复现、期望、实际、环境）
  *
  * 所有写操作走「临时文件 + rename」，避免中途崩溃留下半截文档。
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync, } from 'node:fs';
-import { dirname, isAbsolute, join, posix, resolve, sep, win32 } from 'node:path';
+import { dirname, isAbsolute, posix, resolve, sep, win32 } from 'node:path';
 import { describeError } from "../errors.js";
-/** 文档根目录名，工作区内的隐藏目录。 */
-export const DOC_ROOT = '.xirang-ai/dsh-teamflow';
 /**
- * 计算一份文档在工作区内的相对路径。
+ * 计算一份文档在文档根内的相对路径。
  *
  * @param kind - 文档种类
  * @param ids - 该种类需要的标识（designDoc 需要需求 id 与文档 id）
@@ -27,17 +24,17 @@ export function docPath(kind, ids) {
     const id = requireId(ids.id);
     switch (kind) {
         case 'requirement':
-            return `${DOC_ROOT}/requirements/${id}/requirement.md`;
+            return `requirements/${id}/requirement.md`;
         case 'story':
-            return `${DOC_ROOT}/stories/${id}/story.md`;
+            return `stories/${id}/story.md`;
         case 'bug':
-            return `${DOC_ROOT}/bugs/${id}/bug.md`;
+            return `bugs/${id}/bug.md`;
         case 'designDoc':
-            return `${DOC_ROOT}/requirements/${requireId(ids.requirementId)}/docs/${id}.md`;
+            return `requirements/${requireId(ids.requirementId)}/docs/${id}.md`;
     }
 }
 /**
- * 把相对路径拼到工作区根上；只接受插件自己生成的、以 `/` 分隔的工作区相对路径。
+ * 把相对路径拼到文档根上；只接受插件自己生成的、以 `/` 分隔的文档相对路径。
  *
  * 拒绝 POSIX 绝对路径、Windows 盘符/UNC/反斜杠路径与任何 `..`，最后再做一次
  * 词法 containment 校验，确保结果仍落在 `root` 之内。
@@ -46,10 +43,10 @@ export function resolveDocPath(root, relative) {
     if (relative.length === 0)
         throw new Error('teamflow: document path is empty');
     if (relative.includes('\0') || relative.includes('\\')) {
-        throw new Error(`teamflow: document path must be workspace-relative, got "${relative}"`);
+        throw new Error(`teamflow: document path must be relative to the document root, got "${relative}"`);
     }
     if (isAbsolute(relative) || win32.isAbsolute(relative) || /^[A-Za-z]:/.test(relative)) {
-        throw new Error(`teamflow: document path must be workspace-relative, got "${relative}"`);
+        throw new Error(`teamflow: document path must be relative to the document root, got "${relative}"`);
     }
     const segments = relative.split('/');
     if (segments.some((part) => part === '..' || part === '.' || part.length === 0)) {
@@ -58,27 +55,23 @@ export function resolveDocPath(root, relative) {
     const base = resolve(root);
     const absolute = resolve(base, ...segments);
     if (absolute !== base && !absolute.startsWith(`${base}${sep}`)) {
-        throw new Error(`teamflow: document path escapes the workspace, got "${relative}"`);
+        throw new Error(`teamflow: document path escapes the document root, got "${relative}"`);
     }
     return absolute;
 }
-/** 工作区路径 + 相对路径的展示形式（日志与工具结果用，始终 `/`）。 */
+/** 文档相对路径的展示形式（日志与工具结果用，始终 `/`）。 */
 export function displayPath(relative) {
     return relative.split(sep).join(posix.sep);
 }
 /**
- * 首次为一个工作区准备文档目录：建目录、写 `.gitignore`、必要时把 `.xirang-ai/`
- * 追加进工作区自己的 `.gitignore`。
+ * 首次为文档根准备共享目录：只建 `requirements/`、`stories/`、`bugs/`，
+ * 不碰工作区，也不写 `.gitignore`。
  *
- * @param root - 工作区根目录（绝对路径）
+ * @param root - 文档根目录（绝对路径）
  * @returns 实际创建的目录（相对路径），便于工具结果里说明
  */
 export function ensureDocTree(root) {
-    const dirs = [
-        `${DOC_ROOT}/requirements`,
-        `${DOC_ROOT}/stories`,
-        `${DOC_ROOT}/bugs`,
-    ];
+    const dirs = ['requirements', 'stories', 'bugs'];
     const created = [];
     for (const dir of dirs) {
         const absolute = resolveDocPath(root, dir);
@@ -87,11 +80,6 @@ export function ensureDocTree(root) {
             created.push(dir);
         }
     }
-    const localIgnore = resolveDocPath(root, `${DOC_ROOT}/.gitignore`);
-    if (!existsSync(localIgnore)) {
-        writeFileSync(localIgnore, '*\n', 'utf8');
-    }
-    appendWorkspaceGitignore(root);
     return created;
 }
 /**
@@ -144,8 +132,8 @@ let stagedSequence = 0;
  * 到临时名，再在 SQLite 事务里删记录：事务失败就把文件改回来，事务成功才真正
  * `unlink`。这样任何时刻都不会出现「记录已经没了、正式路径上的文件还在」的悬挂态。
  *
- * @param root - 工作区根目录
- * @param relative - 文档的工作区相对路径
+ * @param root - 文档根目录
+ * @param relative - 文档相对路径
  * @returns 暂存信息；文件本来就不存在时返回 `null`
  */
 export function stageDocDeletion(root, relative) {
@@ -182,10 +170,10 @@ export function dropStagedDoc(staged) {
  * 只删空目录：目录里还有别的东西时立刻停下，避免误删用户手工放进来的文件。
  */
 export function pruneEmptyDirectories(root, relative) {
-    const boundary = resolveDocPath(root, DOC_ROOT);
+    const boundary = resolve(root);
     let directory = dirname(resolveDocPath(root, relative));
     // Stop before the shared `requirements/`, `stories/`, `bugs/` roots: those
-    // belong to the workspace tree, not to the record being deleted.
+    // belong to the document tree, not to the record being deleted.
     while (directory !== boundary && dirname(directory) !== boundary && directory.startsWith(`${boundary}${sep}`)) {
         try {
             if (readdirSync(directory).length > 0)
@@ -211,18 +199,3 @@ function requireId(id) {
     }
     return id;
 }
-/** 把 `.xirang-ai/` 追加到工作区 `.gitignore`；没有该文件就创建一个只含这一行的。 */
-function appendWorkspaceGitignore(root) {
-    const ignore = join(root, '.gitignore');
-    const entry = '.xirang-ai/';
-    if (!existsSync(ignore)) {
-        writeFileSync(ignore, `${entry}\n`, 'utf8');
-        return;
-    }
-    const current = readFileSync(ignore, 'utf8');
-    const lines = current.split('\n').map((line) => line.trim());
-    if (lines.includes(entry) || lines.includes('.xirang-ai'))
-        return;
-    const suffix = current.endsWith('\n') || current.length === 0 ? '' : '\n';
-    writeFileSync(ignore, `${current}${suffix}${entry}\n`, 'utf8');
-}

package/lib/store/model.d.ts

@@ -198,6 +198,27 @@ export interface RequirementSession {
     readonly linkedAt: string | null;
     readonly createdAt: string;
 }
+/** Which kind of record a discussion conversation belongs to. */
+export declare const DISCUSSION_SUBJECT_TYPES: readonly ["requirement", "story", "bug"];
+export type DiscussionSubjectType = (typeof DISCUSSION_SUBJECT_TYPES)[number];
+/** Discussion kind used by stories and defects; requirements keep their own kinds. */
+export declare const GENERAL_DISCUSSION_KIND = "discuss";
+/**
+ * One conversation registered against a requirement, story or defect.
+ *
+ * Rows start unconfirmed (`linkedAt` null) when the browser prepares a
+ * discussion and become visible once the Agent confirms with `linkedAt`.
+ */
+export interface DiscussionSession {
+    readonly subjectType: DiscussionSubjectType;
+    readonly subjectId: string;
+    readonly sessionId: string;
+    /** `create` / `design` / `detail` / `split` for requirements, `discuss` otherwise. */
+    readonly kind: string;
+    readonly preparedAt: string | null;
+    readonly linkedAt: string | null;
+    readonly createdAt: string;
+}
 /**
  * One consistent read of every table the workbench renders.
  *
@@ -214,6 +235,8 @@ export interface BoardRows {
     readonly docStories: readonly DocStoryLink[];
     /** Requirement conversations, newest first; design rows may still be unconfirmed. */
     readonly requirementSessions: readonly RequirementSession[];
+    /** Confirmed story and defect discussions, newest first. */
+    readonly discussionSessions: readonly DiscussionSession[];
 }
 /** Input for {@link WorkflowStore.createDesignDoc}. */
 export interface CreateDesignDocInput {

package/lib/store/model.js

@@ -41,6 +41,10 @@ export const BUG_SEVERITIES = ['blocker', 'critical', 'major', 'minor', 'trivial
 export const DOC_KINDS = ['flow', 'data', 'interface', 'page', 'rule'];
 /** Why a requirement is linked to a conversation. */
 export const REQUIREMENT_SESSION_KINDS = ['create', 'design', 'detail', 'split'];
+/** Which kind of record a discussion conversation belongs to. */
+export const DISCUSSION_SUBJECT_TYPES = ['requirement', 'story', 'bug'];
+/** Discussion kind used by stories and defects; requirements keep their own kinds. */
+export const GENERAL_DISCUSSION_KIND = 'discuss';
 /** A rejected domain operation, separate from SQLite or Host failures. */
 export class WorkflowError extends Error {
     /** Machine-readable reason for tools and the Web UI. */

package/lib/store/paths.d.ts

@@ -2,6 +2,8 @@
 export declare const PLUGIN_HOME_SEGMENTS: readonly ["xirang-ai", "dsh-teamflow"];
 /** Database file name inside the plugin data directory. */
 export declare const DATABASE_FILENAME = "teamflow.sqlite";
+/** Directory name of the markdown documents below the plugin data directory. */
+export declare const DOCS_DIRNAME = "docs";
 /** Human-readable directory of the durable data, e.g. `$DSH_HOME/xirang-ai/dsh-teamflow`. */
 export declare function defaultDataDir(): string;
 /**
@@ -13,6 +15,24 @@ export declare function defaultDataDir(): string;
  * @returns the absolute data directory.
  */
 export declare function resolveDataDir(configured?: string): string;
+/** Default document root: `<dataDir>/docs`, next to the database. */
+export declare function defaultDocsDir(dataDir: string): string;
+/**
+ * Resolve the document root: an explicit `Config.docsDir` wins, otherwise
+ * `<dataDir>/docs`. Relative overrides resolve against the process working
+ * directory and `~/` is expanded, mirroring {@link resolveDataDir}.
+ *
+ * Validation is loud on purpose: a malformed override or a path that is
+ * already a file fails plugin load with the field name and the accepted forms
+ * instead of silently falling back to the default directory.
+ *
+ * @param configured - `Config.docsDir`, possibly empty.
+ * @param dataDir - the resolved data directory.
+ * @returns the absolute document root.
+ */
+export declare function resolveDocsDir(configured: string | undefined, dataDir: string): string;
+/** Create the document root (owner-only) and return it. */
+export declare function ensureDocsDir(docsDir: string): string;
 /** Absolute database file path for a resolved data directory. */
 export declare function databaseFile(dataDir: string): string;
 /** Create the data directory (owner-only) and return it. */

package/lib/store/paths.js

@@ -9,13 +9,16 @@
  * @module
  */
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths';
-import { mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve, sep } from 'node:path';
+import { describeError } from "../errors.js";
 /** Path segments below `$DSH_HOME` that this plugin owns. */
 export const PLUGIN_HOME_SEGMENTS = ['xirang-ai', 'dsh-teamflow'];
 /** Database file name inside the plugin data directory. */
 export const DATABASE_FILENAME = 'teamflow.sqlite';
+/** Directory name of the markdown documents below the plugin data directory. */
+export const DOCS_DIRNAME = 'docs';
 /** Human-readable directory of the durable data, e.g. `$DSH_HOME/xirang-ai/dsh-teamflow`. */
 export function defaultDataDir() {
     return dshHomePath(...PLUGIN_HOME_SEGMENTS);
@@ -38,6 +41,56 @@ export function resolveDataDir(configured) {
         return join(homedir(), trimmed.slice(2));
     return resolve(trimmed);
 }
+/** Default document root: `<dataDir>/docs`, next to the database. */
+export function defaultDocsDir(dataDir) {
+    return join(dataDir, DOCS_DIRNAME);
+}
+/**
+ * Resolve the document root: an explicit `Config.docsDir` wins, otherwise
+ * `<dataDir>/docs`. Relative overrides resolve against the process working
+ * directory and `~/` is expanded, mirroring {@link resolveDataDir}.
+ *
+ * Validation is loud on purpose: a malformed override or a path that is
+ * already a file fails plugin load with the field name and the accepted forms
+ * instead of silently falling back to the default directory.
+ *
+ * @param configured - `Config.docsDir`, possibly empty.
+ * @param dataDir - the resolved data directory.
+ * @returns the absolute document root.
+ */
+export function resolveDocsDir(configured, dataDir) {
+    const trimmed = configured?.trim() ?? '';
+    if (trimmed === '')
+        return defaultDocsDir(dataDir);
+    const expected = 'an absolute path, a path relative to the working directory, or a path starting with "~/"';
+    if (trimmed.includes('\0')) {
+        throw new Error(`teamflow: config "docsDir" must be ${expected}, got ${JSON.stringify(configured)}`);
+    }
+    let absolute;
+    if (trimmed === '~') {
+        absolute = homedir();
+    }
+    else if (trimmed.startsWith(`~${sep}`) || trimmed.startsWith('~/')) {
+        absolute = join(homedir(), trimmed.slice(2));
+    }
+    else {
+        absolute = resolve(trimmed);
+    }
+    if (existsSync(absolute) && !statSync(absolute).isDirectory()) {
+        throw new Error(`teamflow: config "docsDir" must point to a directory, but ${toDisplayPath(absolute)} is a file`);
+    }
+    return absolute;
+}
+/** Create the document root (owner-only) and return it. */
+export function ensureDocsDir(docsDir) {
+    try {
+        mkdirSync(docsDir, { recursive: true, mode: 0o700 });
+    }
+    catch (error) {
+        throw new Error(`teamflow: could not create the docs directory ${toDisplayPath(docsDir)} (config "docsDir"): ${describeError(error)}`, { cause: error });
+    }
+    return docsDir;
+}
 /** Absolute database file path for a resolved data directory. */
 export function databaseFile(dataDir) {
     return join(dataDir, DATABASE_FILENAME);

package/lib/store/schema.js

@@ -22,7 +22,12 @@
  */
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { DOC_ROOT } from "./docs.js";
+/**
+ * Document root of the released v10 migration. Migrations are a historical
+ * contract: v10 moved bodies into the workspace, and that path must stay
+ * exactly as published even though current documents live elsewhere.
+ */
+const LEGACY_DOC_ROOT = '.xirang-ai/dsh-teamflow';
 /**
  * Roles every fresh database starts with. `name` is the default label; the
  * Workbench UI localizes built-in keys through its locale dictionaries, so a
@@ -564,7 +569,7 @@ function relocateV10Bodies(db, designs, docs) {
             updateRequirement.run(primary.contentPath, requirementId);
             continue;
         }
-        const target = `${DOC_ROOT}/requirements/${requirementId}/requirement.md`;
+        const target = `${LEGACY_DOC_ROOT}/requirements/${requirementId}/requirement.md`;
         try {
             let body = readFileSync(absolute(root, primary.contentPath), 'utf8');
             for (const extra of group.slice(1)) {
@@ -589,7 +594,7 @@ function relocateV10Bodies(db, designs, docs) {
         const root = roots.get(requirementId);
         if (root === undefined || doc.contentPath === '')
             continue;
-        const target = `${DOC_ROOT}/requirements/${requirementId}/docs/${doc.id}.md`;
+        const target = `${LEGACY_DOC_ROOT}/requirements/${requirementId}/docs/${doc.id}.md`;
         try {
             if (!existsSync(absolute(root, doc.contentPath)))
                 continue;
@@ -809,6 +814,50 @@ const SCHEMA_V16 = `
 ALTER TABLE stories ADD COLUMN create_session_id TEXT;  -- 创建该故事的 DSH 会话 id；历史数据为 NULL
 ALTER TABLE bugs ADD COLUMN create_session_id TEXT;  -- 创建该缺陷的 DSH 会话 id；历史数据为 NULL
 `;
+/**
+ * v17：讨论会话登记泛化为需求 / 故事 / 缺陷三类对象。
+ *
+ * 需求专属的 `requirement_sessions` 只能挂需求，而故事与缺陷也要能从详情页
+ * 发起讨论并回写正文。这里换成一张按 `(subject_type, subject_id, session_id)`
+ * 唯一的通用表：需求侧原有的 kind（create/design/detail/split）原样迁入，
+ * 故事与缺陷用 `discuss`。时间列沿用旧表的 TEXT ISO-8601，迁移不换算。
+ * 对象删除不再级联：列表按 `(subject_type, subject_id)` 查询，孤儿行不进任何列表。
+ */
+const SCHEMA_V17 = `
+CREATE TABLE discussion_sessions (                 -- 讨论对象与宿主会话的登记关系表
+  subject_type TEXT NOT NULL,                      -- 讨论对象类型：requirement / story / bug
+  subject_id   TEXT NOT NULL,                      -- 讨论对象 id（需求 / 故事 / 缺陷的业务 id）
+  session_id   TEXT NOT NULL,                      -- 宿主会话 id
+  kind         TEXT NOT NULL DEFAULT 'discuss',    -- 讨论类型：discuss 为通用讨论；需求侧沿用既有取值
+  prepared_at  TEXT,                               -- 两段式登记第一段：客户端写入的「待开始」时刻（ISO-8601 UTC）；创建会话行为 NULL
+  linked_at    TEXT,                               -- 两段式登记第二段：Agent 确认后的「已登记」时刻（ISO-8601 UTC）；NULL = 待开始
+  created_at   TEXT NOT NULL,                      -- 行首次创建时刻（ISO-8601 UTC）
+  PRIMARY KEY (subject_type, subject_id, session_id)
+);
+
+CREATE INDEX idx_discussion_sessions_subject
+  ON discussion_sessions (subject_type, subject_id, linked_at DESC);
+`;
+/** Copy every legacy requirement row into the generic table and drop it. */
+function migrateRequirementSessions(db) {
+    db.exec(SCHEMA_V17);
+    db.exec(`
+INSERT INTO discussion_sessions
+  (subject_type, subject_id, kind, session_id, prepared_at, linked_at, created_at)
+SELECT 'requirement', requirement_id, kind, session_id, prepared_at, linked_at, created_at
+FROM requirement_sessions;
+`);
+    const before = db.prepare('SELECT COUNT(*) AS count FROM requirement_sessions').get();
+    const after = db
+        .prepare("SELECT COUNT(*) AS count FROM discussion_sessions WHERE subject_type = 'requirement'")
+        .get();
+    const copied = Number(after?.['count'] ?? 0);
+    const expected = Number(before?.['count'] ?? 0);
+    if (copied !== expected) {
+        throw new Error(`teamflow: schema migration 17 copied ${copied} requirement session row(s) but the legacy table held ${expected}; rolling back`);
+    }
+    db.exec('DROP TABLE requirement_sessions');
+}
 export const MIGRATIONS = [
     {
         version: 1,
@@ -944,6 +993,13 @@ export const MIGRATIONS = [
             db.exec(SCHEMA_V16);
         },
     },
+    {
+        version: 17,
+        description: 'generalize discussion sessions to requirements, stories and bugs',
+        up: (db) => {
+            migrateRequirementSessions(db);
+        },
+    },
 ];
 /** Schema version this build expects; the last migration's version. */
 export const TARGET_SCHEMA_VERSION = MIGRATIONS.at(-1)?.version ?? 0;
@@ -985,24 +1041,25 @@ export const SCHEMA_COMMENTS = [
     { table: 'requirements', column: 'workspace_id', description: '所属 DSH 工作区 id（ctx.workspaces 的 WorkspaceView.workspaceId）；空串表示 v4 迁移之前写入的历史数据。' },
     { table: 'requirements', column: 'title', description: '需求标题。' },
     { table: 'requirements', column: 'summary', description: '澄清并总结后的一句话结论，供详细设计和故事引用。' },
-    { table: 'requirements', column: 'content_path', description: '正文（需求 + 概要设计）相对路径（工作区内，如 .xirang-ai/dsh-teamflow/requirements/<id>/requirement.md）。' },
+    { table: 'requirements', column: 'content_path', description: '正文（需求 + 概要设计）相对路径（文档根内，如 requirements/<id>/requirement.md）。' },
     { table: 'requirements', column: 'status', description: '状态：draft=进行中（仍在收集或修改），completed=用户确认完成，archived=已归档；完成不会自动发生。' },
     { table: 'requirements', column: 'created_at', description: '创建时间（ISO-8601 UTC）。' },
     { table: 'requirements', column: 'updated_at', description: '最后更新时间（ISO-8601 UTC）。' },
     { table: 'requirements', column: 'completed_at', description: '用户确认完成需求的时间（ISO-8601 UTC），未完成为 NULL。' },
-    { table: 'requirement_sessions', column: '', description: '需求与会话：创建需求（create）、概要设计讨论（design）、详细设计讨论（detail）和故事拆分讨论（split）都记在这里。' },
-    { table: 'requirement_sessions', column: 'requirement_id', description: '所属需求；删除需求时级联清理关联。' },
-    { table: 'requirement_sessions', column: 'session_id', description: 'DSH 会话 id，唯一；一个会话只属于一个需求。' },
-    { table: 'requirement_sessions', column: 'kind', description: '会话类型：create=创建需求，design=讨论概要设计，detail=讨论详细设计，split=讨论故事拆分。' },
-    { table: 'requirement_sessions', column: 'prepared_at', description: '浏览器创建讨论会话后写入待登记的时间（ISO-8601 UTC）；创建需求的会话为 NULL。' },
-    { table: 'requirement_sessions', column: 'linked_at', description: 'Agent 调用登记工具确认的时间（ISO-8601 UTC）；NULL 表示待开始，不进入历史列表。' },
-    { table: 'requirement_sessions', column: 'created_at', description: '首次绑定时间（ISO-8601 UTC）。' },
+    { table: 'discussion_sessions', column: '', description: '讨论对象与宿主会话的登记关系：需求、故事、缺陷的讨论会话都记在这里，两段式登记（浏览器准备、Agent 确认）。' },
+    { table: 'discussion_sessions', column: 'subject_type', description: '讨论对象类型：requirement=需求，story=故事，bug=缺陷；与 subject_id 一起标识对象。' },
+    { table: 'discussion_sessions', column: 'subject_id', description: '讨论对象 id（需求 / 故事 / 缺陷的业务 id）；对象删除时不级联清理。' },
+    { table: 'discussion_sessions', column: 'session_id', description: 'DSH 会话 id；同一对象与同一会话只有一行。' },
+    { table: 'discussion_sessions', column: 'kind', description: '讨论类型：create=创建需求，design=讨论概要设计，detail=讨论详细设计，split=讨论故事拆分，discuss=故事/缺陷的通用讨论。' },
+    { table: 'discussion_sessions', column: 'prepared_at', description: '浏览器创建讨论会话后写入待登记的时间（ISO-8601 UTC）；创建需求的会话为 NULL。' },
+    { table: 'discussion_sessions', column: 'linked_at', description: 'Agent 调用登记工具确认的时间（ISO-8601 UTC）；NULL 表示待开始，不进入历史列表。' },
+    { table: 'discussion_sessions', column: 'created_at', description: '首次绑定时间（ISO-8601 UTC）。' },
     { table: 'stories', column: '', description: '故事：可独立开发与交付的单元；父级是需求，也可以独立存在。' },
     { table: 'stories', column: 'id', description: 'nanoid 业务主键（sty_ 前缀）。' },
     { table: 'stories', column: 'workspace_id', description: '所属 DSH 工作区 id：有父级时继承并校验一致，独立故事创建时指定。' },
     { table: 'stories', column: 'requirement_id', description: '所属需求；为空表示用户直接提出的独立故事。' },
     { table: 'stories', column: 'title', description: '故事标题。' },
-    { table: 'stories', column: 'content_path', description: '故事正文相对路径：说明与验收标准写在同一份 story.md 里。' },
+    { table: 'stories', column: 'content_path', description: '故事正文相对路径（文档根内，如 stories/<id>/story.md）：说明与验收标准写在同一份 story.md 里。' },
     { table: 'stories', column: 'status', description: '状态：ready=待开发，developing=开发中，self_testing=自测中，done=执行完毕（未完成），completed=用户确认完成，cancelled=已取消。' },
     { table: 'stories', column: 'size', description: '拆分时的工作量档位：xs/s/m/l/xl。' },
     { table: 'stories', column: 'sort_order', description: '同一需求下的展示顺序，升序；新建取当前最大值 + 1，运行与状态流转不改它。' },
@@ -1013,7 +1070,7 @@ export const SCHEMA_COMMENTS = [
     { table: 'design_docs', column: 'requirement_id', description: '所属需求；删除需求时一并删除其文档。' },
     { table: 'design_docs', column: 'kind', description: '文档主题：flow=流程，data=数据，interface=接口，page=页面，rule=规则。' },
     { table: 'design_docs', column: 'title', description: '文档标题，工作台列表中一行显示。' },
-    { table: 'design_docs', column: 'content_path', description: '详设正文相对路径；正文很长，只落盘不进库。' },
+    { table: 'design_docs', column: 'content_path', description: '详设正文相对路径（文档根内，如 requirements/<req>/docs/<doc>.md）；正文很长，只落盘不进库。' },
     { table: 'design_docs', column: 'sort_order', description: '同一需求下的展示顺序，升序；新建取当前最大值 + 1，页面只按它渲染。' },
     { table: 'design_docs', column: 'created_at', description: '创建时间（ISO-8601 UTC）。' },
     { table: 'design_docs', column: 'updated_at', description: '最后更新时间（ISO-8601 UTC）。' },
@@ -1028,7 +1085,7 @@ export const SCHEMA_COMMENTS = [
     { table: 'bugs', column: 'id', description: 'nanoid 业务主键（bug_ 前缀）。' },
     { table: 'bugs', column: 'workspace_id', description: '所属 DSH 工作区 id：bug 独立存在，创建时必须显式给出。' },
     { table: 'bugs', column: 'title', description: 'bug 标题。' },
-    { table: 'bugs', column: 'content_path', description: '缺陷正文相对路径：描述、复现、期望、实际、环境都在这份 bug.md 里。' },
+    { table: 'bugs', column: 'content_path', description: '缺陷正文相对路径（文档根内，如 bugs/<id>/bug.md）：描述、复现、期望、实际、环境都在这份 bug.md 里。' },
     { table: 'bugs', column: 'severity', description: '严重程度：blocker/critical/major/minor/trivial。' },
     { table: 'bugs', column: 'status', description: '状态：reported=待修复，fixing=修复中，fixed=执行完毕（未完成），completed=用户确认完成，wontfix=不修复。' },
     { table: 'bugs', column: 'resolution', description: '修复结论、不修复原因或关闭说明。' },

package/lib/store/workflow.d.ts

@@ -19,17 +19,16 @@
  */
 import type { DatabaseSync } from 'node:sqlite';
 import { type PermissionTier } from '../permission-tier.ts';
-import { type Bug, type BugFilter, type BoardRows, type DeletePreview, type DeleteReport, type DeleteTarget, type CreateBugInput, type CreateDesignDocInput, type CreateRequirementInput, type CreateStoryInput, type DesignDoc, type FinishRunInput, type Requirement, type RequirementSession, type RequirementSessionKind, type UpdateDesignDocInput, type RequirementFilter, type Run, type RunFilter, type StartRunInput, type Story, type StoryFilter, type StoryReadiness, type UpdateBugInput, type UpdateRequirementInput, type UpdateStoryInput } from './model.ts';
+import { type Bug, type BugFilter, type BoardRows, type DeletePreview, type DeleteReport, type DeleteTarget, type DiscussionSession, type DiscussionSubjectType, type CreateBugInput, type CreateDesignDocInput, type CreateRequirementInput, type CreateStoryInput, type DesignDoc, type FinishRunInput, type Requirement, type RequirementSession, type RequirementSessionKind, type UpdateDesignDocInput, type RequirementFilter, type Run, type RunFilter, type StartRunInput, type Story, type StoryFilter, type StoryReadiness, type UpdateBugInput, type UpdateRequirementInput, type UpdateStoryInput } from './model.ts';
 /** Cap one batch so a single call cannot scan an unbounded id list. */
 export declare const MAX_DELETE_TARGETS = 50;
 /** Construction options for {@link WorkflowStore}. */
 export interface WorkflowStoreOptions {
     /**
-     * Root that holds `requirements/`, `stories/` and `bugs/` when a workspace
-     * directory is not known yet. Production wiring passes the
-     * workspace path instead (see {@link WorkflowStore.registerWorkspace}).
+     * Absolute document root that holds `requirements/`, `stories/` and
+     * `bugs/`. Every body lives here; records only store the root-relative path.
      */
-    readonly docsRoot?: string;
+    readonly docsRoot: string;
     /** Resolver used before the registry; lets the Host provide the live path. */
     readonly workspaceRoot?: (workspaceId: string) => string | undefined;
     /** Clock override for tests; must return an ISO-8601 UTC string. */
@@ -45,52 +44,78 @@ export interface WorkflowStoreOptions {
  */
 export declare class WorkflowStore {
     #private;
-    constructor(db: DatabaseSync, options?: WorkflowStoreOptions);
+    constructor(db: DatabaseSync, options: WorkflowStoreOptions);
     /**
-     * Remember where a workspace lives on disk. Documents are written into that
-     * directory, so this must be called before the first file-backed write;
-     * repeated calls with the same path are no-ops.
+     * Remember where a workspace lives on disk. Document bodies no longer live
+     * there, but the path is still recorded for display and for future
+     * workspace-scoped features; repeated calls with the same path are no-ops.
      */
     registerWorkspace(workspaceId: string, path: string): void;
-    /** Directory a workspace's documents live in, or null when unknown. */
+    /** Directory a registered workspace lives in, or null when unknown. */
     workspacePath(workspaceId: string): string | null;
     /**
-     * Read a document body by its workspace-relative path.
+     * Read a document body by its document-root-relative path.
      *
      * `null` means the file does not exist; `''` means it exists and is empty.
-     * A workspace without a directory is a configuration error, not a missing
-     * document, so it is reported as `file_error` instead of being folded into
-     * either empty result.
+     * Every record resolves against the one configured document root, so a
+     * legacy path simply misses instead of falling back to a workspace.
      */
-    readContent(workspaceId: string, relativePath: string): string | null;
+    readContent(relativePath: string): string | null;
     /** Rewrite a document body; the path comes from the row, so it is always current. */
-    writeContent(workspaceId: string, relativePath: string, body: string): void;
+    writeContent(relativePath: string, body: string): void;
     getRequirement(id: string): Requirement | null;
     listRequirements(filter?: RequirementFilter): Requirement[];
     /**
      * Register a browser-created session as a pending discussion for a requirement.
      *
+     * Kept as a thin wrapper over {@link prepareDiscussionSession} so the
+     * requirement page and its tests keep their existing shape.
+     */
+    prepareRequirementSession(requirementId: string, sessionId: string, kind?: RequirementSessionKind): RequirementSession;
+    /**
+     * Register a browser-created session as a pending discussion for a subject.
+     *
      * The browser creates the session first, then calls this before the user can
      * send the first message. The row stays invisible in `listBoard` until the
-     * Agent confirms it through {@link linkRequirementSession}.
+     * Agent confirms it through `teamflow_link_session`; this method never writes
+     * `linked_at`, so the client cannot skip Agent confirmation.
      */
-    prepareRequirementSession(requirementId: string, sessionId: string, kind?: RequirementSessionKind): RequirementSession;
+    prepareDiscussionSession(subjectType: DiscussionSubjectType, subjectId: string, sessionId: string, kind: string): DiscussionSession;
     /**
-     * Confirm the current session as a discussion of the requirement prepared for it.
+     * Confirm the current session as the discussion it was prepared for.
      *
-     * Called by `teamflow_link_requirement_session`; repeated calls are idempotent
-     * so a model retry cannot create duplicate history rows.
+     * Called by `teamflow_link_session`; repeated calls are idempotent so a model
+     * retry cannot rewrite the confirmation time.
+     */
+    linkDiscussionSession(sessionId: string): DiscussionSession;
+    /**
+     * Confirm the current session as a requirement discussion.
+     *
+     * Kept for `teamflow_link_requirement_session`; new callers use
+     * {@link linkDiscussionSession}.
      */
     linkRequirementSession(sessionId: string): RequirementSession;
-    /** Pending or linked conversation prepared for one session, or null. */
+    /** Pending or linked requirement conversation prepared for one session, or null. */
     getRequirementSession(sessionId: string): RequirementSession | null;
     /** The requirement linked to a session, whichever kind of link it is. */
     getRequirementBySession(sessionId: string): Requirement | null;
+    /** The discussion row bound to one session, or null when none exists. */
+    getDiscussionSession(sessionId: string): DiscussionSession | null;
+    /**
+     * Discussions under one subject, newest linked first.
+     *
+     * Pending rows are excluded by default so the workbench never shows a session
+     * the Agent has not started; tests and diagnostics can opt in.
+     */
+    listDiscussionSessions(subjectType: DiscussionSubjectType, subjectId: string, options?: {
+        readonly includeUnlinked?: boolean;
+        readonly kinds?: readonly string[];
+    }): DiscussionSession[];
     /**
-     * Conversations under one requirement, newest linked first.
+     * Requirement conversations under one requirement, newest linked first.
      *
-     * Pending design rows are excluded by default so the workbench never shows a
-     * session the Agent has not started; tests and diagnostics can opt in.
+     * The `create` row is always included: it explains where the requirement came
+     * from even though the Agent never confirms it.
      */
     listRequirementSessions(requirementId: string, options?: {
         readonly includePending?: boolean;