@istuen/pt 0.1.0

package/src/asset-pack/md-file-pack.ts

@@ -0,0 +1,202 @@
+// src/asset-pack/md-file-pack.ts — AssetPack 的文件系统实现（v15.x PR1）
+//
+// 设计源：.pt/docs/designs/pt-asset-pack.md §2.3（MdFilePack）
+//
+// 与 src/parse/{domain,blueprint,profile}.ts 现有 parser 复用，不重写 parse 算法。
+// AssetPack 只是把"目录"封装成可命名、可版本化的单元。
+//
+// PR1 简化（按 PR1.2 + PR1.6 文档）：
+//   - name 由构造传入（reserved 固定名 "prj"/"gbl"/"pt"，PR4 接通后 settings pack 走 basename 兜底）
+//   - version / description 固定占位（PR2 接通 manifest 后从 manifest 读）
+//   - loadXxx 内 parse 失败的文件返 null 后 filter 掉——**不**调 reportWarn/reportError
+//     （那些是 adapterCtx 依赖；PR1 的 MdFilePack 内部错误由 validatePack 层捕获，见 PR1.6）
+//   - loadXxx 不接 adapterCtx 参数（AssetPack interface 不暴露）——
+//     parseProfile 内 modName 解析失败的 warn 通道在本 PR 阶段丢失（已知 PR1 简化，
+//     不影响 pack 加载本身；后续 PR 可选把 adapterCtx 透传回 parseProfile）
+
+import { basename as pathBasename } from "node:path";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { SUFFIX_BLUEPRINT_YAML, SUFFIX_MD } from "../constants.js";
+import { errMsg, reportError } from "../diagnostics.js";
+import type {
+  AssetPack,
+  Blueprint,
+  Domain,
+  PackSource,
+  Profile,
+  SourceAdapterContext,
+} from "../schema.js";
+import { parseBlueprint } from "../parse/blueprint.js";
+import { parseDomain } from "../parse/domain.js";
+import { parseProfile } from "../parse/profile.js";
+import { parseManifest } from "./manifest.js";
+
+/**
+ * v15.x PR2：文件系统 Pack 实现——读 <rootDir>/{domains,blueprints,profiles}/。
+ * 与 src/parse/{domain,blueprint,profile}.ts 现有 parser 共用，不重写 parse 算法。
+ *
+ * PR2：构造从 sync 改 async（读 manifest），走 `MdFilePack.create()` 工厂方法。
+ * name 解析优先级（§2.4.2）：
+ *   - reserved pack（source=project/global/builtin）→ 固定名 prj/gbl/pt，跳过 manifest
+ *   - 显式 pack + 合法 manifest.name → manifest.name
+ *   - 隐式 pack（无 manifest / manifest 无 name / name 校验失败）→ basename 兜底
+ *
+ * PR1 补丁（S2 修复）：构造可选接 adapterCtx——loadXxx 内部 parse 失败时调
+ *           reportError，恢复 v10.x 旧 loadDir 行为的"错误可见性"。未传则 fallback
+ *           console.error（diagnostics.ts:reportError 三通道 fallback）。
+ */
+export class MdFilePack implements AssetPack {
+  readonly name: string;
+  readonly version: string; // PR2：从 manifest 读（缺失则 "0.0.0"）
+  readonly rootDir: string;
+  readonly description: string | undefined; // PR2：从 manifest 读（缺失则 undefined）
+  readonly source: PackSource;
+  /** adapterCtx 可选——parse 失败时调 reportError 走 notify + log 通道。 */
+  private readonly adapterCtx: SourceAdapterContext | undefined;
+
+  private constructor(args: {
+    rootDir: string;
+    name: string;
+    version: string;
+    description?: string;
+    source: PackSource;
+    adapterCtx?: SourceAdapterContext;
+  }) {
+    this.rootDir = args.rootDir;
+    this.name = args.name;
+    this.version = args.version;
+    this.description = args.description;
+    this.source = args.source;
+    this.adapterCtx = args.adapterCtx;
+  }
+
+  /** 位置别名退化表（v15.x §2.4.2 缺口 1-b）：reserved pack 无 manifest 时 name 退化到位置别名。
+   *  用途：back-compat——今天无 manifest 的项目 pack.name 仍是 prj/gbl/pt，行为等价。 */
+  private static readonly RESERVED_FALLBACK_NAME: ReadonlyMap<PackSource, string> = new Map([
+    ["project", "prj"],
+    ["global", "gbl"],
+    ["builtin", "pt"],
+  ]);
+
+  /** PR2（v15.x §2.4.2 双层语义）：工厂方法（async，读 manifest）。
+   *  所有 pack 都走 manifest 解析；reserved pack 无 manifest 时 name 退化到位置别名（back-compat）。
+   *  - manifest.name 优先（身份 alias）
+   *  - reserved pack 无 manifest → 退化到 RESERVED_FALLBACK_NAME.get(source)
+   *  - 非 reserved pack 无 manifest → basename 兜底 */
+  static async create(args: {
+    rootDir: string;
+    source: PackSource;
+    adapterCtx?: SourceAdapterContext;
+  }): Promise<MdFilePack> {
+    const manifest = await parseManifest(args.rootDir);
+    const dirName = pathBasename(args.rootDir);
+
+    // manifest warnings 上抛 notify（不阻断——parseManifest 已容错）
+    if (manifest.warnings.length > 0 && args.adapterCtx?.notify) {
+      args.adapterCtx.notify(
+        `Pt: pack "${dirName}" manifest 警告：${manifest.warnings.join("; ")}`,
+        "warning"
+      );
+    }
+
+    // name 解析优先级（§2.4.2）：
+    //   1. manifest.name（身份 alias 优先）
+    //   2. reserved pack 无 manifest → 退化到位置别名（prj/gbl/pt，back-compat）
+    //   3. 非 reserved 无 manifest → basename 兜底
+    const fallbackName = MdFilePack.RESERVED_FALLBACK_NAME.get(args.source) ?? dirName;
+    const name = manifest.name ?? fallbackName;
+
+    return new MdFilePack({
+      rootDir: args.rootDir,
+      name,
+      version: manifest.version ?? "0.0.0",
+      description: manifest.description,
+      source: args.source,
+      adapterCtx: args.adapterCtx,
+    });
+  }
+
+  async loadDomains(): Promise<Domain[]> {
+    const dir = join(this.rootDir, "domains");
+    return loadDomainsRecursive(dir, this.adapterCtx);
+  }
+
+  async loadBlueprints(): Promise<Blueprint[]> {
+    const dir = join(this.rootDir, "blueprints");
+    return loadDir(dir, SUFFIX_BLUEPRINT_YAML, (f) => parseBlueprint(dir, f), this.adapterCtx);
+  }
+
+  async loadProfiles(): Promise<Profile[]> {
+    const dir = join(this.rootDir, "profiles");
+    const profiles = await loadDir(
+      dir,
+      SUFFIX_MD,
+      (f) => parseProfile(dir, f, this.adapterCtx),
+      this.adapterCtx
+    );
+    // v15.x PR3（§4.4.1）：MdFilePack 加载时给每个 Profile 打上 sourcePack——parseRef 不限定 ref 自动绑定用。
+    for (const p of profiles) {
+      p.sourcePack = this.name;
+    }
+    return profiles;
+  }
+}
+
+// ==================== 共享加载辅助（PR1 内部，未来抽到独立模块） ====================
+
+/** 顶层目录加载：只扫顶层文件（Blueprint/Profile 不递归——避免破坏现有结构）。
+ *  parse 失败的文件：调 reportError 上抛 notify + log（恢复 v10.x 旧 loadDir 行为，
+ *  PR1 补丁 S2 修复），未传 adapterCtx 时 fallback console.error。
+ *  目录不存在返空数组（与现有 loadDir 行为一致）。 */
+async function loadDir<T>(
+  dir: string,
+  suffix: string,
+  parser: (f: string) => Promise<T>,
+  adapterCtx: SourceAdapterContext | undefined
+): Promise<T[]> {
+  let files: string[];
+  try {
+    files = (await readdir(dir)).filter((f) => f.endsWith(suffix));
+  } catch {
+    return []; // 目录不存在返空
+  }
+  const results: Array<T | null> = await Promise.all(
+    files.map(async (f): Promise<T | null> => {
+      try {
+        return await parser(f);
+      } catch (e) {
+        reportError(adapterCtx, `parse ${dir}/${f} failed: ${errMsg(e)}`, { file: f });
+        return null;
+      }
+    })
+  );
+  return results.filter((r): r is T => r !== null);
+}
+
+/** 递归加载 domains/ 下所有 .md（多级目录支持）。
+ *  Node.js 20+ readdir({ recursive: true }) 跨平台统一返回 POSIX '/' 分隔路径。
+ *  Domain.name = POSIX 相对路径去 .md（支持 "workflow/dev-workflow" 等多级命名）。
+ *  parse 失败的文件：调 reportError 上抛（PR1 补丁 S2）。 */
+async function loadDomainsRecursive(
+  dir: string,
+  adapterCtx: SourceAdapterContext | undefined
+): Promise<Domain[]> {
+  let files: string[];
+  try {
+    files = (await readdir(dir, { recursive: true })).filter((f) => f.endsWith(SUFFIX_MD));
+  } catch {
+    return []; // 目录不存在返空
+  }
+  const results: Array<Domain | null> = await Promise.all(
+    files.map(async (relPath) => {
+      try {
+        return await parseDomain(dir, relPath);
+      } catch (e) {
+        reportError(adapterCtx, `parse ${dir}/${relPath} failed: ${errMsg(e)}`, { file: relPath });
+        return null;
+      }
+    })
+  );
+  return results.filter((r): r is Domain => !!r);
+}

package/src/asset-pack/validate.ts

@@ -0,0 +1,186 @@
+// src/asset-pack/validate.ts — Pack 校验（v15.x PR1）
+//
+// 设计源：.pt/docs/designs/pt-asset-pack.md §6.7.2（两层校验）/ §6.7.7（不抛异常）
+//
+// 关键纪律：validatePack 永远返结果对象，不抛异常——失败不阻断加载链。
+// 错误收集到 errors[] / warnings[]，返 ok: boolean。
+//
+// 层 1（pack 结构）：rootDir 存在 + 至少一个 asset 子目录
+// 层 2（asset 解析）：loadDomains/loadBlueprints/loadProfiles 不抛即过
+//
+// PR1 简化：
+//   - 不做 manifest 校验（PR2）
+//   - 不做 pack 内同 name asset 冲突检测（PR2 与 manifest 校验一起做）
+//   - 不做 settings pack 之间冲突报错（PR4 接通 settings 加载时一起做）
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { errMsg } from "../diagnostics.js";
+import type { AssetPack } from "../schema.js";
+
+/** v15.x §2.4.4（位置 alias 表）：reserved pack 的位置别名。reserved pack 才有，非 reserved 为 undefined。
+ *  UI 显示层用——reserved 显位置别名，settings 显 pack 名（§4.4.4 双层语义）。 */
+const RESERVED_ALIAS: ReadonlyMap<AssetPack["source"], "prj" | "gbl" | "pt"> = new Map([
+  ["project", "prj"],
+  ["global", "gbl"],
+  ["builtin", "pt"],
+]);
+
+/** 校验结果（§6.7.7）。validatePack 永远返结果对象，不抛异常。 */
+export interface ValidationResult {
+  /** Pack 名（来源 pack.name——manifest.name 或退化别名） */
+  pack: string;
+  /** Pack 来源类型 */
+  source: AssetPack["source"];
+  /** v15.x §4.4.4（缺口 4）：reserved pack 的位置别名（prj/gbl/pt），非 reserved 为 undefined。
+   *  UI 显示层用——reserved 显位置别名，settings 显 pack 名。 */
+  reservedAlias?: "prj" | "gbl" | "pt";
+  /** 整体是否可用 */
+  ok: boolean;
+  /** 致命问题（pack 不可用） */
+  errors: PackIssue[];
+  /** 非致命（pack 可用但有隐患——目前未使用，预留扩展） */
+  warnings: PackIssue[];
+  /** v15.x PR2（§6.7.6 展示用）：pack version。 */
+  version: string;
+  /** v15.x PR2（§6.7.6 展示用）：pack description（可选）。 */
+  description?: string;
+  /** v15.x PR2（§6.7.6 展示用）：pack rootDir。 */
+  rootDir: string;
+}
+
+/** 单条校验问题。code 机器可读，msg 人类可读，hint 修复建议。 */
+export interface PackIssue {
+  /** 机器可读错误码（如 "dir-not-found"） */
+  code: string;
+  /** 人类可读 */
+  msg: string;
+  /** 修复建议（可选） */
+  hint?: string;
+}
+
+/**
+ * 两层校验（§6.7.2）：
+ *   层 1 pack 结构：rootDir 存在 + 至少一个 asset 子目录
+ *   层 2 asset 解析：loadDomains/loadBlueprints/loadProfiles 不抛即过
+ *     （parse 失败的文件已在 MdFilePack 内部 filter 掉，不阻断 pack 加载）
+ *
+ * 永远返结果对象，不抛异常（§6.7.7）——失败不阻断加载链。
+ */
+export async function validatePack(pack: AssetPack): Promise<ValidationResult> {
+  const errors: PackIssue[] = [];
+  const warnings: PackIssue[] = [];
+
+  // 层 1：pack 结构——目录存在
+  if (!existsSync(pack.rootDir)) {
+    errors.push({
+      code: "dir-not-found",
+      msg: `pack 目录不存在: ${pack.rootDir}`,
+      hint: "检查路径配置，或创建该目录（参考 /manual:pack-repair）",
+    });
+    return {
+      pack: pack.name,
+      source: pack.source,
+      reservedAlias: RESERVED_ALIAS.get(pack.source),
+      ok: false,
+      errors,
+      warnings,
+      version: pack.version,
+      rootDir: pack.rootDir,
+    };
+  }
+
+  // 层 1：pack 结构——至少一个 asset 子目录
+  const hasDomains = existsSync(join(pack.rootDir, "domains"));
+  const hasBlueprints = existsSync(join(pack.rootDir, "blueprints"));
+  const hasProfiles = existsSync(join(pack.rootDir, "profiles"));
+  if (!hasDomains && !hasBlueprints && !hasProfiles) {
+    errors.push({
+      code: "no-asset-subdir",
+      msg: `pack "${pack.name}" 无任何 asset 子目录（domains/blueprints/profiles）`,
+      hint: "至少创建一个 asset 子目录（参考 /manual:pack-repair）",
+    });
+    return {
+      pack: pack.name,
+      source: pack.source,
+      reservedAlias: RESERVED_ALIAS.get(pack.source),
+      ok: false,
+      errors,
+      warnings,
+      version: pack.version,
+      rootDir: pack.rootDir,
+    };
+  }
+
+  // 层 2：asset 解析 + pack 内一致性（§6.7.2 补全）
+  try {
+    const domains = await pack.loadDomains();
+    const blueprints = await pack.loadBlueprints();
+    const profiles = await pack.loadProfiles();
+    // v15.x PR2（§6.7.2 层 2）：同 Pack 内同 name asset 冲突检测
+    checkIntraPackConflicts("domain", domains, errors);
+    checkIntraPackConflicts("blueprint", blueprints, errors);
+    checkIntraPackConflicts("profile", profiles, errors);
+  } catch (e) {
+    errors.push({
+      code: "load-failed",
+      msg: `pack "${pack.name}" 加载失败: ${errMsg(e)}`,
+      hint: "检查资产文件格式（参考 /manual:pack-repair）",
+    });
+  }
+
+  // pack 内一致性（同 name asset 冲突）—— v15.x PR2 在层 2 已做（checkIntraPackConflicts）
+
+  return {
+    pack: pack.name,
+    source: pack.source,
+    reservedAlias: RESERVED_ALIAS.get(pack.source),
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    version: pack.version,
+    description: pack.description,
+    rootDir: pack.rootDir,
+  };
+}
+
+/** v15.x PR2（§6.7.2 层 2）：同 Pack 内同 name asset 冲突检测。
+ *  重复 name 报错——同 Pack 内 asset name 必须唯一。
+ *  不检测跨 Pack 冲突（那是 dedupByNameN 的职责，前者赢）。 */
+function checkIntraPackConflicts<T extends { name: string }>(
+  kind: string,
+  assets: T[],
+  errors: PackIssue[]
+): void {
+  const seen = new Map<string, number>();
+  for (const a of assets) {
+    const count = seen.get(a.name) ?? 0;
+    if (count > 0) {
+      errors.push({
+        code: "intra-pack-conflict",
+        msg: `pack 内 ${kind} "${a.name}" 重复（${count + 1} 次）`,
+        hint: `同 Pack 内 ${kind} name 必须唯一——重命名或删除重复文件`,
+      });
+    }
+    seen.set(a.name, count + 1);
+  }
+}
+
+/**
+ * v15.x PR1（§7.5 + §7.5.1）：判断是否该弹全局 Pack 初始化引导。
+ * pure helper——抽出来让 session_start handler 简洁，也便于单元测试。
+ *
+ * 约束：TTY + 目录不存在 + 首次（每个 session 只提示一次）+ 非 CI + 非 PT_NO_GUIDE 禁用。
+ * 调用方负责检查 isFirstRun（读 session state.globalPackGuideShown）和传 env。
+ */
+export function shouldPromptGlobalPackGuide(args: {
+  isTTY: boolean;
+  globalPackExists: boolean;
+  isFirstRun: boolean;
+  isCi: boolean;
+  guideDisabled: boolean;
+}): boolean {
+  return (
+    args.isTTY && !args.globalPackExists && args.isFirstRun && !args.isCi && !args.guideDisabled
+  );
+}

package/src/builtin/assets/blueprints/dev-knowledge.blueprint.yaml

@@ -0,0 +1,13 @@
+name: dev-knowledge
+groups:
+  - name: 会话背景
+    inject: session
+    mode: hybrid
+    # v9.1（modules-to-profile 迁移）：modules 字段已删除——由 Profile `### Modules` 提供
+    # Phase term-P8：会话参与者信息段——user-info Domain 的 H3 项（user-profile/pt-goal/collab-mode 等）走 Participant
+  - name: 触发索引
+    inject: session
+    # 桥接 Session↔Turn：把有什么手册、何时查作为索引注入，每轮 LLM 可见
+  - name: 参考手册
+    inject: turn
+    # Phase term-P9.2：Manual 拆三段——Rules / Flows / Checklists

package/src/builtin/assets/domains/agent-info.md

@@ -0,0 +1,15 @@
+---
+name: agent-info
+---
+
+# agent-info
+
+## Agent
+### role
+- desc: 你是 Pt 引导下的编码助手——理解 Pt 资产结构，帮用户创作/修改 Domain 与 Profile
+
+### collaboration
+- desc: 用户=需求方+决策者（主导方向）；你=方案推理者+可行性验证者+代码/文档实现者
+
+### boundaries
+- desc: 不自行发挥架构方向；改资产前先读 authoring 的格式规范；改完删 cache 重编译验证

package/src/builtin/assets/domains/authoring.md

@@ -0,0 +1,201 @@
+---
+name: authoring
+---
+
+# authoring
+
+## Trigger
+### authoring-trigger
+- desc: 创作/修改 Pt 资产 md 时参考；含 Pt Domain/Blueprint/Pt Profile 格式（v9.1+） + 创建流程 + 角色隔离配置
+- hint: /manual:authoring 查看完整创作手册
+
+## Scene
+
+### domain-format
+- desc: frontmatter（name: 域路径名——根目录写裸名 `user-info`，多级目录写 path 形式 `workflow/dev-workflow`，与加载路径一致；无 type 字段——Module/H2 段名即 schema 选择器）+ Module（## Scene / ## Trigger / ## Rules / ## Flows / ## Checklists / ## Participant / ## User / ## Agent / ...，按需写）+ H3 项（### 项名 + - desc: 描述 / - path: 路径 / - check: 规则 / - fields: 字段清单 / - note: 补充说明）。文件放 .pt/assets/domains/<name>.md 或 .pt/assets/domains/<subdir>/<name>.md。
+
+### blueprint-format
+- desc: YAML 格式（.blueprint.yaml）。字段：name + groups（聚合组列表，每个含 name + inject: session/turn + mode）。**v9.1+：Blueprint 不带 modules 字段**——Blueprint 退化为插槽契约（声明有哪些插槽 + inject + mode），modules 由 Profile H2 下的 ### Modules 列表填。无 agent 字段（Blueprint Agent-agnostic，运行时硬编码 "pi"）。无 Compilation 段（cacheDir 用 CACHE_DIR 常量）。文件放 .pt/assets/blueprints/<name>.blueprint.yaml（v9.1+ 可省略——`src/parse/index.ts` 的 `dedupByName` 机制保证项目优先 + 内建补充，profile 引 `blueprint: dev-knowledge` 自动 fallback 到 builtin）。
+
+### profile-format
+- desc: frontmatter（name + blueprint: 引用名 + domains: [全局 Domain 列表，**多级目录用 path 形式**如 `workflow/dev-workflow`，自动分发到所有聚合组]）+ H2 聚合组实例化（## 聚合组名 与 Blueprint.groups[].name 同名）+ H3 段下两类追加列表：(a) `### Domains` 追加到本聚合组的 Domain 名列表；(b) `### Modules` 本插槽填的 modName 列表（v9.1+）。**v9.1+ 的 modules 形态 2 种**：段名（`Scene` / `User`）和 段.项（`Agent.senior-developer`），无形态 3。domains 顺序影响 LLM attention——身份类放前，约束类放后。文件放 .pt/assets/profiles/<name>.profile.md。
+
+### profile-modules-section
+- desc: v9.1+ Profile H2 段下 ### Modules 段填法——按 modName 2 形态逐行列出本插槽的 modules。**形态 1：段名**（整段聚合，跨所有引用域）——例 `- Scene`（所有引用域的 Scene 段都进）。**形态 2：段.项**（精确选 H3 项）——例 `- Agent.agent-role-senior-developer`（agent-info 段下 senior-developer 项进）。modName 解析失败（段名不在 `KNOWN_SECTION_NAMES` 集合）→ log warn 跳过。**解析规则**：`Scene` / `User.user-profile` / `Trigger.authoring-trigger` 都合法；`my-domain:Scene.foo` 这种形态 3 形式不合法——限定到单 domain 用专用段名（`User` / `Agent`）。
+
+### profile-section-namespace
+- desc: 段名 = 命名空间（v9.1+）——通用段（`Scene` / `Trigger` / `Rules` / `Flows` / `Checklists`）跨 domain 通用；专用段（`User` / `Agent`）限定到单 domain（`user-info` 用 `User`、`agent-info` 用 `Agent`）。**Profile 角色隔离的核心机制**——专用段名让 profile 可以"只选自己需要的身份角色"而不影响其他 profile。例：pt-arch 与 pt-dev 共享同一 agent-info Domain（6 个 H3 项：architect / senior-developer / qa-engineer / code-reviewer / devops-engineer / active-role-rule），但 pt-arch `### Modules: [Agent.agent-role-architect, Agent.active-role-rule]` 只看到 architect + active-role-rule；pt-dev `### Modules: [Agent.agent-role-senior-developer, Agent.agent-role-qa-engineer, Agent.agent-role-code-reviewer, Agent.active-role-rule]` 只看到 dev 3 角色 + active-role-rule。
+
+### profile-role-isolation
+- desc: v9.1+ Profile 角色隔离配置示例（共享 agent-info Domain，各 profile 只看自己角色 + active-role-rule）：
+- sample-pt-arch: |
+    ## 会话背景
+    ### Modules
+    - Scene
+    - User
+    - Agent.agent-role-architect
+    - Agent.active-role-rule
+- sample-pt-design: |
+    ## 会话背景
+    ### Modules
+    - Scene
+    - User
+    - Agent.agent-role-architect
+    - Agent.active-role-rule
+- sample-pt-dev: |
+    ## 会话背景
+    ### Modules
+    - Scene
+    - User
+    - Agent.agent-role-senior-developer
+    - Agent.agent-role-qa-engineer
+    - Agent.agent-role-code-reviewer
+    - Agent.active-role-rule
+- sample-pt-devops: |
+    ## 会话背景
+    ### Modules
+    - Scene
+    - User
+    - Agent.agent-role-devops-engineer
+    - Agent.active-role-rule
+- step: 复制 sample 改 name + domains + ### Modules 即可
+
+### profile-multi-level-dir
+- desc: 多级目录引用（v9.1+）——Profile frontmatter `domains:` 列表用 path 形式引用多级目录的 Domain。例：`.pt/assets/domains/workflow/dev-workflow.md` → `domains: [user-info, agent-info, workflow/dev-workflow, workflow/issue-workflow, workflow/testing-workflow, ...]`。**同目录不重名**（硬约束，文件系统约束）；不同子目录可同名（path 天然区分——`meta/login` 和 `auth/login` 不冲突）。Domain frontmatter.name 也用 path 形式（与加载路径一致）。
+
+### profile-h2-sections
+- desc: Profile 范本必加 H2 聚合组段——即使无追加也保留段让配置入口可见。具体格式：YAML 后用 H2 标题写出 Blueprint.groups[].name 同名的段；段下用 `### Domains` 追加（如有）+ `### Modules` 列本插槽的 modules 列表（v9.1+）。例如 pt-dev 范本保留 ## 会话背景 + ## 触发索引 + ## 参考手册 三段（与 dev-knowledge 的 groups 对齐）。配置可观测性：parseProfile groups 数 > 0，用户能看出本 Profile 覆盖哪些聚合组 + 每个聚合组的 modules 选择。
+
+### term-domain-pattern
+- desc: 概念/术语/规则类 Domain 写法：## Scene 下 ### 概念名 + - desc: 定义；## Rules 下 ### 规则名 + - check: 不变量描述。适合概念/术语/架构知识。（注：v9 已删 type 字段，不再有 term/workflow/stack 分类——H2 段名决定 schema。）
+
+### workflow-domain-pattern
+- desc: 流程/手册类 Domain 写法：## Scene 下 ### 引用名 + - path: 路径 + - desc: 说明；## Flows 下 ### 流程名 + - intent: 目的 + - step: 步骤。适合操作流程/开发手册。（注：v9 已删 type 字段。）
+
+### participant-domain-pattern
+- desc: 身份类 Domain 写法（v9.1+ 重命名）——user-info Domain 用 `## User` 段下 H3 角色项（user-profile / pt-goal / collab-mode / ...）；agent-info Domain 用 `## Agent` 段下 H3 角色项（agent-role-architect / agent-role-senior-developer / ...）。**段名 = 命名空间**：`User` 限定 user-info、`Agent` 限定 agent-info。Profile 通过 `### Modules: [User]` 聚合 user-info 整段；通过 `### Modules: [Agent.agent-role-architect]` 精确选单角色——角色隔离的"开关"。
+
+### build-roadmap
+- desc: 从零构建 Pt 资产的顺序：（1）分析项目知识结构（参考 project-analysis 的 analyze-steps + section-as-namespace + role-isolation）→ 识别概念/流程/工具栈；（2）创建 Pt Domain 资产（每个知识单元一个 .md，H2 段名决定 schema）→ create-domain-procedure；（3）选 Blueprint（优先复用内建 dev-knowledge，聚合组需求不同才 create-blueprint-procedure——v9.1+ 通常省略，dedupByName 自动 fallback 到 builtin）→（4）创建 Pt Profile 组装 Domain 列表 + ### Modules 填 H3 粒度 → create-profile-procedure；（5）/pt-profile 验证产物 + 检查角色隔离。执行 procedure 时用 /pt manual <procedure-name> <args> 创建实例文档跟踪。
+
+### minimal-example
+- desc: 从零上手的最小样本——两个 Domain（user-info + agent-info）+ 一个 Profile，照抄改即可跑通
+- sample-domain-user: |
+    ---
+    name: user-info
+    ---
+    # user-info
+    ## User
+    ### who-am-i
+    - desc: 我是这个项目的开发者
+
+    ### preferences
+    - desc: 偏好类型安全、模块化设计
+- sample-domain-agent: |
+    ---
+    name: agent-info
+    ---
+    # agent-info
+    ## Agent
+    ### role
+    - desc: 你是编码助手，帮用户创作 Pt 资产
+- sample-profile: |
+    ---
+    name: my-guide
+    blueprint: dev-knowledge
+    domains: [user-info, agent-info, project-analysis, authoring, usage]
+    ---
+    # my-guide (profile)
+    ## 会话背景
+    ### Modules
+    - Scene
+    - User
+    - Agent
+    ## 触发索引
+    ### Modules
+    - Trigger
+    ## 参考手册
+    ### Modules
+    - Rules
+    - Flows
+    - Checklists
+- steps: 放 user-info.md / agent-info.md 到 .pt/assets/domains/，放 my-guide.profile.md 到 .pt/assets/profiles/，/pt-profile my-guide 激活
+- why: 展示最小闭环——两个 Domain 各只写 User/Agent 段（用户身份 + Agent 身份，v9.1+ 重命名），Profile 引内建 blueprint + 选域 + 填 ### Modules 段含 `User` / `Agent` 整段（onboarding 完整模式）；激活后 Session Context 即有成对身份
+
+### renderer-registration
+- desc: 加新专用段名（如 `## Audit` / `## Glossary`）的扩展流程——(1) Domain 内用新 H2 段名；(2) `src/parse/profile.ts` 的 `KNOWN_SECTION_NAMES` 集合加新段名一行；(3) `src/compile/agent-context.ts` 的 `moduleRenderers` 注册一行（已有 renderer 复用，如复用 `renderSceneModule` 处理 Term[] 同构）；(4) `src/constants.ts` 加 `MOD_XXX = "XXX"` 常量一行（可选，但建议加——模块名常量集中管理便于跨文件引用）。**不需要改主循环**——加新 modName 走 renderer 注册表分发，generic fallback 兜底。
+
+## Flows
+
+### create-domain-procedure
+- argument-hint: <name>
+- intent: 创建新 Pt Domain 资产的步骤指引（LLM 读完后用 write 工具执行，非 Pi 注册命令）
+- vars: [name]
+- step: 用 write 工具创建 .pt/assets/domains/{{name}}.md（多级目录可放 .pt/assets/domains/<subdir>/{{name}}.md）
+- step: 写 frontmatter（name: {{name}}——多级目录用 path 形式如 `workflow/dev-workflow`，无 type 字段）
+- step: 按知识性质选 Module（概念→Scene+Rules，流程→Scene+Flows，规则→Rules，验收→Checklists；身份类→User 或 Agent 专用段）
+- step: 在目标 Profile 的 domains 列表追加 {{name}}（多级目录用 path 形式）
+- step: 删 .pt/cache/agent-contexts/*.agent-context.md + /pt-profile <profile> 验证
+
+### create-profile-procedure
+- argument-hint: <name>
+- intent: 创建新 Pt Profile 的步骤指引（LLM 读完后用 write 工具执行，非 Pi 注册命令）
+- vars: [name]
+- step: 用 write 工具创建 .pt/assets/profiles/{{name}}.profile.md
+- step: 写 frontmatter（name: {{name}} + blueprint: dev-knowledge 优先复用内建 + domains: [按需列，多级目录用 path 形式]）
+- step: 为每个 Blueprint 插槽加 H2 段（## 会话背景 / ## 触发索引 / ## 参考手册 等），段下加 `### Modules` 列表（v9.1+）填本插槽的 modName（段名 / 段.项两种形态）
+- step: 角色隔离配置——身份域用专用段名 + 段.项精确选单角色（详见 profile-role-isolation 的 sample-pt-arch / pt-dev / pt-devops）
+- step: 删 .pt/cache/agent-contexts/*.agent-context.md + /pt-profile {{name}} 验证产物 + 检查角色隔离
+
+### create-blueprint-procedure
+- argument-hint: <name>
+- intent: 创建新 Blueprint 的步骤指引（v9.1+ 通常省略——优先复用内建；仅当聚合组需求与内建 dev-knowledge 不同时新建；LLM 读完后用 write 工具执行）
+- vars: [name]
+- step: 确认需要新聚合组——dev-knowledge 有会话背景/触发索引/参考手册三个聚合组（session×2 + turn×1），不够才新建
+- step: 用 write 工具创建 .pt/assets/blueprints/{{name}}.blueprint.yaml
+- step: 写 YAML（name: {{name}}，无 agent 字段，**无 modules 字段**——v9.1+ Blueprint 是插槽契约）
+- step: 写 groups（每个聚合组：name + inject: session/turn + mode 可选）——**modules 字段不再存在**
+- step: Profile frontmatter 的 blueprint 字段改为 {{name}} 引用
+- step: Profile H2 段下 ### Modules 列表按需填 modName（段名 / 段.项形态）
+- step: 删 .pt/cache/agent-contexts/*.agent-context.md + /pt-profile <profile> 验证
+
+### modify-asset-procedure
+- argument-hint: (无)
+- intent: 修改已有资产的步骤指引（LLM 读完后用 edit/write 工具执行）
+- vars: []
+- step: 用 read 工具读目标 .md（Pt Domain/Blueprint/Pt Profile）
+- step: 用 edit 工具改内容（或 write 整体重写）—— Profile 改 ### Modules 时保持 modName 2 形态
+- step: 删 .pt/cache/agent-contexts/*.agent-context.md（强制重编译）
+- step: /pt-profile <profile> 重载验证
+- step: 检查产物：/pt raw 看 segment，确认角色隔离生效（pt-dev 不含 architect / devops-engineer，pt-arch 不含 senior+qa+cr+devops 等）
+
+## Rules
+
+### when-new-domain
+- check: 主题聚焦才建新 Domain——一个 Domain 承载一个知识单元；同主题扩内容加 Module，不新建 Domain
+
+### when-new-blueprint
+- check: 聚合组需求不同才建 Blueprint——优先复用内建 dev-knowledge（会话背景/触发索引/参考手册三组）；加新聚合组才新建。**v9.1+：Blueprint 不带 modules，创建后无需同步 modules 字段到 Profile——Profile 填 ### Modules 独立维护**
+
+### when-add-module
+- check: 同主题扩内容加 Module（Domain 内加 ## 新 Module 名）；不同主题才新建 Domain
+
+### section-name-namespace
+- check: 段名是命名空间（v9.1+）——通用段（Scene/Trigger/Rules/Flows/Checklists）跨 domain 通用；专用段（User/Agent/...）限定到单 domain。加新专用段 = 同时改 Domain + KNOWN_SECTION_NAMES + moduleRenderers（详见 renderer-registration）
+
+### multi-level-dir-no-collision
+- check: 同目录不重名（v9.1+ 多级目录硬约束）——`domains/meta/login.md` 与 `domains/meta/login-other.md` OK（不同名），但 `domains/meta/login.md` 与 `domains/auth/login.md` 也 OK（path 不同），仅 `domains/meta/login.md` 与 `domains/meta/login.md` 冲突（重复）。不同子目录同名用 path 形式引用时不会冲突。
+
+### role-isolation-via-section-name
+- check: 角色隔离通过专用段名实现（v9.1+）——user-info 用 ## User、agent-info 用 ## Agent，Profile 引用 `[User]` 整段或 `[Agent.<role>]` 精确选。**不要在 modName 里加形态 3（domain:段.项）**——会破坏命名空间设计且 profile 配置冗余。
+
+## Checklists
+
+### domain-quality-checklist
+- items: [frontmatter name 对齐加载路径（多级目录用 path 形式）, H2 段名是标准段（Scene/Trigger/Rules/Flows/Checklists）或已注册专用段（User/Agent/...）, H3 项有 desc 字段, 同段内 H3 项名唯一（跨段可重名靠专用段名避免）, 无 type 字段]
+
+### profile-quality-checklist
+- items: [blueprint 引用名存在（优先内建 dev-knowledge）, domains 顺序合理（身份类前约束类后）, 聚合组段对齐 Blueprint groups（每个 group 一个 H2）, ### Modules 段存在且填了 modName（v9.1+ 必填）, modName 是合法 2 形态（段名 / 段.项），不含形态 3, 角色隔离正确：专用段（User/Agent）按设计填充，段.项精确选单角色, 无追加时保留 H2 段让配置入口可见, 多级目录引用用 path 形式（如 `workflow/dev-workflow`）]
+
+### role-isolation-checklist
+- items: [4 profile（pt-arch / pt-design / pt-dev / pt-devops）共用同一 agent-info Domain 但各自 ### Modules 列出不同 Agent 角色, pt-dev `### Modules` 含 `Agent.agent-role-senior-developer` + `Agent.agent-role-qa-engineer` + `Agent.agent-role-code-reviewer` + `Agent.active-role-rule`（不含 architect / devops-engineer）, pt-arch / pt-design 含 `Agent.agent-role-architect` + `Agent.active-role-rule`（不含 dev / devops 角色）, pt-devops 含 `Agent.agent-role-devops-engineer` + `Agent.active-role-rule`（不含其他角色）, 跑 transpile 后 /pt raw 检查产物——`### agent-info.senior-developer` 等 H3 粒度输出仅在应见 profile 中出现]

package/src/builtin/assets/domains/pack-repair.md

@@ -0,0 +1,47 @@
+---
+name: pack-repair
+---
+
+# pack-repair
+
+v15.x PR1（§6.7.4）：project pack 校验失败时的修复引导手册。builtin profile `guide`
+会引用本 domain——用户 `/manual:pack-repair` 触发 FlowTemplate，按步骤修复。
+
+## Scene
+
+### pack-structure
+- desc: Pt pack 标准目录结构——必须含 domains/ + blueprints/ + profiles/ 三个子目录之一；可选 pt-asset-pack.yaml manifest（PR2 启用）
+
+### pack-sources
+- desc: v15.x Pack 有 4 类来源——project（`<cwd>/.pt/assets/`）/ settings（`.pi/settings.json` 的 `pt.asset-packs[]`，PR4 启用）/ global（`~/.pt/assets/`）/ builtin（`src/builtin/assets/`，随 npm 包发布）
+
+### validation-codes
+- desc: validatePack 返回的错误码——`dir-not-found`（路径不存在）/ `no-asset-subdir`（无 asset 子目录）/ `load-failed`（加载抛异常）
+
+## Flows
+
+### pack-repair
+- argument-hint: (无)
+- intent: project pack 校验失败时引导修复——按错误码分类处置后重启 session 验证
+- vars: []
+- step: /pt status 查看 pack 健康状态（§6.7.6），定位失效 pack + 错误码
+- step: 按 errors[].code 分类处置：
+  - dir-not-found：创建 pack 目录（project: mkdir -p .pt/assets/{domains,blueprints,profiles}；global: mkdir -p ~/.pt/assets/{domains,blueprints,profiles}）
+  - no-asset-subdir：至少创建一个 asset 子目录（domains/blueprints/profiles 任选其一）
+  - load-failed：检查资产文件格式（.md frontmatter 合法 / .blueprint.yaml 语法正确）
+- step: 修复后重启 pi session（projectPackDegraded 在 session_start 重新校验时清零）
+- step: /pt status 确认 pack 健康（✅，无 DEGRADED 行）
+
+## Rules
+
+### validate-pack-never-throws
+- check: validatePack 失败时返 ValidationResult 对象（ok=false + errors[]），不抛异常——保证加载链不阻断（§6.7.7）
+
+### project-pack-degradation
+- check: project pack 失效时强制激活 builtin guide profile（projectPackDegraded=true），覆盖用户配置的 pt.default-profile——保证 pi 可用让用户修复（§6.7.3）
+
+### restart-after-repair
+- check: 修复 project pack 后必须重启 pi session——projectPackDegraded 标记在 session_start 重新校验时清零，不重启则继续降级
+
+### global-pack-guide-non-interactive
+- check: 全局 Pack 初始化引导仅在 TTY + 非 CI + 无 PT_NO_GUIDE 环境触发（§7.5.1）——避免阻塞 CI / 后台进程