@istuen/pt 0.1.0

package/dist/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 / 后台进程

package/dist/builtin/assets/domains/project-analysis.md

@@ -0,0 +1,52 @@
+---
+name: project-analysis
+---
+
+# project-analysis
+
+## Scene
+
+### what-is-pt
+- desc: Pt 是异构上下文编译器——把领域知识按配置编译成 Agent 上下文并注入。你写 .pt/assets/ 下的 Pt Domain（知识原料）和 Pt Profile（配置），Pt 编译成 Agent Context（Session Context 固定注入面 + Turn Context 按需触发面），注入 Agent。
+
+### four-layer-model
+- desc: Pt Domain（内容层——一个 md = 一个知识单元，Module/H2 段名即 schema 选择器）+ Blueprint（结构层——聚合组插槽契约 name + inject + mode，跨项目复用，YAML 载体）+ Pt Profile（配置层——引用 Blueprint + 选 Domains + 填 modules，项目级）+ Agent Context（产物层——编译输出，Session Context + Turn Context 两面，带 sourceHash 缓存）。**v9.1+：Blueprint 不带 modules（退化为插槽契约）——modules 由 Profile 的 H2 段下 ### Modules 列表提供。**
+
+### analyze-steps
+- desc: 识别项目知识结构的三步法：（1）列举项目里的领域概念/术语 → Domain 用 Scene + Rules Module；（2）列举项目里的操作流程/开发手册 → Domain 用 Scene + Flows Module；（3）列举项目用的技术栈/工具 → Domain 用 Scene Module（带 path 字段引用外部资源）。一个 Domain 可混装多种 Module，不必按类型拆分。
+
+### aggregation-group
+- desc: Blueprint 的 groups 定义聚合组（语义名，如"会话背景"/"触发索引"/"参考手册"），inject 字段映射到注入位置（session = 每轮固定 / turn = 轮次级按需触发）。**v9.1+**：Blueprint groups 不带 modules（插槽契约），modules 由 Profile H2 段下 ### Modules 列表填——Profile 通过 H2 名匹配 Blueprint 插槽，每 H2 下的 ### Modules 列本插槽的 modules 列表（段名 / 段.项 两种形态）。AgentAdapter 内部映射 session/turn 到 Pi API（system_prompt/context_message）。
+
+### modname-2-forms
+- desc: modName 2 形态（v9.1+）——(1) 段名（`Scene` / `User` / `Agent` / `Trigger` / `Rules` / `Flows` / `Checklists`）：跨所有引用域该段整段聚合；(2) 段.项（`Agent.senior-developer` / `User.user-profile`）：跨所有引用域该段下 H3 项精确选。**不引入形态 3（domain:段.项）**——限定到单 domain 通过专用段名（`User` / `Agent`）实现，避免 profile 重复写引用。
+
+### section-as-namespace
+- desc: 段名 = 命名空间（v9.1+）——通用段（Scene / Participant / Trigger / Rules / Flows / Checklists）跨 domain 通用；专用段（User / agent-info 用 / Agent / agent-info 用 / ...）限定到单 domain。加新专用段 = Domain 用新 H2 段名 + `KNOWN_SECTION_NAMES` 集合加一行 + `moduleRenderers` 注册一行（详见 authoring 的 renderer-registration）。
+
+### multi-level-dir
+- desc: 多级目录支持（v9.1+）——`.pt/assets/domains/<subdir>/<name>.md` 用子目录归类相关 Domain。`loadAllDomains` 自动递归扫描；Domain.name = POSIX 相对路径去 .md（`workflow/dev-workflow`）。Profile 的 `domains:` 列表用 path 形式引用——`[user-info, agent-info, workflow/dev-workflow, ...]`。**同目录不重名**（硬约束，文件系统约束）；不同子目录可同名（path 天然区分）。
+
+### role-isolation
+- desc: 角色隔离（v9.1+ 核心承诺）——通过专用段名 + 段.项粒度实现 Profile 间的角色隔离。例：pt-dev profile 用 `[Scene, User, Agent.agent-role-senior-developer, Agent.agent-role-qa-engineer, Agent.agent-role-code-reviewer, Agent.active-role-rule]`——只看 dev 3 角色 + active-role-rule，不看 architect / devops-engineer；pt-arch 用 `[Scene, User, Agent.agent-role-architect, Agent.active-role-rule]`；pt-devops 用 `[Scene, User, Agent.agent-role-devops-engineer, Agent.active-role-rule]`。**4 profile 共享同一 Blueprint（dev-knowledge）+ 同一 Domain 集合（user-info + agent-info + ...），差异全在 ### Modules 段——真正的隔离**。
+
+### h3-name-uniqueness
+- desc: H3 项名唯一约束（v9.1+）——同段内 H3 重名 parse 时**后覆盖前**（保持 IR 唯一性）；跨段同名 H3 由段名命名空间避免（`Scene.x` 不匹配 `User` 段下同名 x，要跨段匹配必须改段名）。**`### <domain>.<item>` 渲染形式**——H3 项粒度产物输出形式（如 `### agent-info.senior-developer`）。
+
+### inv-domain-granularity
+- desc: 一个 Domain 承载一个知识单元——可以混装多种 Module（Scene + Rules + Flows），但语义上聚焦一个主题。按主题拆分 Domain，不按 Module 类型拆分。
+
+### inv-blueprint-reuse
+- desc: Blueprint 是跨项目复用的结构层——不要为单个项目定制 Blueprint；优先复用内建 Blueprint（dev-knowledge，含会话背景/触发索引/参考手册三个聚合组），只在聚合组需求不同时新建。**v9.1+**：Blueprint 是插槽契约（name + inject + mode），不带 modules——modules 来自 Provider。
+
+## Flows
+
+### quickstart-flow
+- argument-hint: (无)
+- intent: 新手 5 步上手引导
+- vars: []
+- step: npm install @issac/pi-pt + 配置 pi.extensions（见 README）
+- step: 激活内建 guide Profile——pi --pt-profile guide，或不设配置装包即自动激活
+- step: /pt 查看当前编译状态（profile + segment 长度 + cache hit）
+- step: 读 project-analysis 的 analyze-steps + section-as-namespace + role-isolation 分析自己项目的知识结构
+- step: /pt flows 列出可触发手册，试 /manual:authoring 查看创作手册

package/dist/builtin/assets/domains/usage.md

@@ -0,0 +1,81 @@
+---
+name: usage
+---
+
+# usage
+
+## Trigger
+### usage-trigger
+- desc: 操作 Pt 时参考；含 /pt 命令族（含 /pt manual 实例化手册）+ --pt-profile flag（--pt-context 为旧 flag，backward-compat 保留）+ /pt-profile 切换
+- hint: /manual:usage 查看完整命令列表
+
+## Scene
+
+### pt-commands
+- desc: /pt（查看当前状态）+ /pt status（profile + segment 长度 + cache hit）+ /pt flows（列出可触发手册，即 Turn Context 内容索引）+ /pt raw（dump segment 到 .pt/cache/raws/）+ /pt full（dump 完整 Session Inject 到 .pt/cache/fulls/）
+
+### pt-profile-command
+- desc: /pt-profile（列出所有可用 Profile）+ /pt-profile <name>（切换到指定 Profile，下一轮生效）。旧命令 /pt-context 保留为 backward-compat fallback。
+
+### manual-trigger
+- desc: /manual:<domain-name>（注入该 Domain 的 Rules/Flows/Checklists 段到 Turn Inject）+ /<flow-name> <args>（触发 Domain 的 FlowTemplate）
+
+### pt-profile-flag
+- desc: --pt-profile <name>（Pi 启动时激活指定 Profile，CLI 优先级高于 session_start 默认逻辑）。旧 flag --pt-context 保留为 backward-compat fallback。
+
+### pt-manual-command
+- desc: /pt manual <procedure-name> [args...]（创建手册实例文档到 .pt/manuals/，含 checklist + 产物区，用于跟踪执行）。与 /manual:<domain>（ephemeral 参考）互补——前者持久化，后者即时注入。
+
+### pt-tools-llm
+- desc: pt_status / pt_flows / pt_manual 三个 LLM tool（pi.registerTool）。与 /pt 命令族共享纯函数内核——人类打 /pt status，LLM 调 pt_status，结果一致。/pt-profile 不做 tool（切换 Profile 改 Session Context 不该让 LLM 触发，见 .pt/docs/designs/pt-command-tool-dual-registration.md §2.4）。
+
+### global-pack
+- desc: v15.x 全局 Pack（~/.pt/assets/，寻址 @gbl）——用户跨项目共用资产放这里，Pt 自动加载（优先级低于 project/settings，高于 builtin）。首次启动如目录不存在会提示创建（TTY + 非 CI + 无 PT_NO_GUIDE 时）。复用方式：把通用 Domain/Blueprint/Profile 放 ~/.pt/assets/{domains,blueprints,profiles}/
+
+### settings-pack
+- desc: v15.x settings 声明 Pack——在 .pi/settings.json 的 pt.asset-packs[] 声明第三方 / 团队 Pack（只 path 字段，name 从 manifest 读）。路径支持 ~（home dir）/ 绝对 / 相对 cwd。多个 settings pack 按声明顺序后者赢（npm 风格）。pt.project-pack-dir 可改 project pack 路径（默认 .pt/assets，支持项目外路径）
+
+### use-profile
+- desc: v15.x Profile use 单继承——use: @pack/name 引用另一 Profile 作为基础增量覆盖。blueprint 覆盖 / tagline 覆盖 / domains 追加去重 / groups 同名替换。循环检测报错含链；菱形不误报。不写 use = 独立 Profile。示例：use: @pt-internal/pt-dev + blueprint: @team-stdlib/minimal + domains: [my-domain]
+
+### frontmatter-parser-limit
+- desc: Profile / Domain 的 frontmatter 是简易 parser（src/parse/shared.ts:parseFrontmatter）——支持单行 key: value，不支持复杂 YAML 结构（多行字符串 / 嵌套 / 注释）。复杂结构走 Blueprint 的 .blueprint.yaml（用 yaml 库完整解析）。v15.x use 字段保持单行 string 形态以兼容（M7）——如 `use: @pt-internal/pt-dev`，不写多行
+
+## Flows
+
+### list-profiles
+- argument-hint: (无)
+- intent: 列出当前项目所有可用 Profile 名（含内建 fallback）
+- vars: []
+- step: 读 .pt/assets/profiles/ 下所有 .profile.md 的 frontmatter.name
+- step: 合并内建 src/builtin/assets/profiles/（同名时项目优先）
+- step: 去重排序后输出
+
+### switch_profile
+- argument-hint: <profile-name>
+- intent: 切换到指定 Profile 并重编译
+- vars: [profile-name]
+- step: /pt-profile {{profile-name}}
+- step: Pt 删该 profile 的 cache（强制重编译）
+- step: 下一轮 Pi 事件自动加载新 profile 的 segment
+
+### dump_segment
+- argument-hint: (无)
+- intent: 把当前 session 的 segment（Pt 注入的 Session Context）dump 到文件
+- vars: []
+- step: /pt raw → 写入 .pt/cache/raws/segment-<timestamp>.md
+- step: 用于检查 Pt 编译产物是否正确
+
+## Rules
+
+### cache-invalidation-rule
+- check: 改资产后必删 .pt/cache/agent-contexts/*.agent-context.md 强制重编译；sourceHash 会自动失效，但手动删 cache 是最直接的验证方式
+
+### profile-switch-next-turn
+- check: /pt-profile <name> 切换后下一轮才生效（before_agent_start 事件重注入）；当前轮不受影响
+
+### module-fallback-warning
+- check: Domain Module 名拼错（如 ## Scenr）会走 generic fallback 静默聚合，不报错；用 /pt raw 检查 segment 确认 Module 是否正确贡献
+
+### builtin-override
+- check: 项目 .pt/assets/ 下同名资产覆盖内建（dedupByName 项目优先）；内建 guide 被项目 guide 覆盖时 /pt status 仍显示 guide 名但内容是项目版

package/dist/builtin/assets/domains/user-info.md

@@ -0,0 +1,15 @@
+---
+name: user-info
+---
+
+# user-info
+
+## User
+### who-am-i
+- desc: 我是这个项目的开发者（修改为你的真实身份）
+
+### preferences
+- desc: 偏好类型安全、模块化架构、数据驱动设计（修改为你的偏好）
+
+### goals
+- desc: 把领域知识资产化，让 Agent 有稳定上下文（修改为你的目标）

package/dist/builtin/assets/profiles/guide.profile.md

@@ -0,0 +1,28 @@
+---
+name: guide
+blueprint: dev-knowledge
+domains: [user-info, agent-info, project-analysis, authoring, usage, pack-repair]
+---
+
+# guide (profile)
+
+<!--
+v9.1+（modules-to-profile-complete）：见 pt-arch.profile.md 头注释。
+guide 是 onboarding——会话背景含 Scene + User 整段 + Agent 整段，展示完整信息。
+-->
+
+## 会话背景
+### Modules
+- Scene
+- User
+- Agent
+
+## 触发索引
+### Modules
+- Trigger
+
+## 参考手册
+### Modules
+- Rules
+- Flows
+- Checklists

package/dist/commands.d.ts

@@ -0,0 +1,69 @@
+import type { SessionState } from "./session.js";
+/** /pt status 内核：返回状态摘要文本（单行 | 分隔）。 */
+export declare function statusText(session: SessionState): string;
+/** v15.x §4.4.4（缺口 5）：/pt packs 详情命令——pack 诊断信息落点。
+ *  pack.name/version/desc/asset 计数走这里，status 单行不再塞 desc。
+ *  asset 计数：从 active bundle 的 workingSet.identity 索引按 pack.name 前缀过滤。 */
+export declare function packsText(session: SessionState): string;
+/** /pt flows 内核：返回可用手册列表文本。无激活 Profile 返回提示串。
+ *
+ * v13.x（issue pt-turn-inject-not-profile-scoped）：不再预过滤——传全集 domains 给 listManuals，
+ * adapter 内部用 setAgentContext 时存下的 profile 自行 filterDomainsByProfile 过滤。 */
+export declare function flowsText(session: SessionState): string;
+/** /pt full 内核：构建写入 .pt/cache/fulls/ 的完整 systemPrompt 字符串（v10.x 修复 pt-full-duplicate-segment）。
+ *
+ * 设计动机：消除 `/pt full` 与 PiAdapter `before_agent_start` 的双重拼接路径——
+ *   - PiAdapter 每轮把 segment 拼到 base，写回 `agent.state.systemPrompt`（= `ctx.getSystemPrompt()`）
+ *   - 第一轮 prompt 之后，`ctx.getSystemPrompt()` 已含 segment；旧版 `/pt full` 再拼一次 → 2× 重复
+ *   - 根因：两份拼接实现通过隐式时序耦合，缺乏单一信息源
+ *
+ * 修复：把 `lastBuiltPrompt`（由 PiAdapter 的 `onInjected` 回调写入，正是 LLM 实际看到的 systemPrompt）
+ *   作为 canonical source。第一轮之前的 fallback：模拟下一次 LLM 会看到的注入（保留旧版语义）。
+ *
+ * 边界纪律：
+ *   - 不动 PiAdapter（PiAdapter 行为正确，不重复注入）
+ *   - 不动 Pi 上游 API（`getSystemPrompt` 语义不变）
+ *   - 只动这一个函数体，外加调用方 `src/index.ts`
+ */
+export declare function buildFullPrompt(baseSystemPrompt: string, cachedSegment: string | null, lastBuiltPrompt: string | null): string;
+/** /pt manual 内核：构建手册实例文档内容 + 目标文件路径。不写文件（写文件由壳负责）。 */
+export interface ManualDocResult {
+    content: string;
+    filePath: string;
+    error?: string;
+}
+export declare function buildManualDoc(cwd: string, session: SessionState, procedure: string, args: string): ManualDocResult;
+/** /pt check 选项（issue pt-asset-migration-visibility Layer 3）。
+ *  - profileName：单 profile 体检（v1 范围；--all 全集是默认）
+ *  - fix：v2 范围（v1 不实现；只输出"运行 `/pt check --fix`"提示）
+ *  v1：format = "biome"（仅一种风格；预留给未来 tsc/eslint 切换）。 */
+export interface CheckOptions {
+    profileName?: string;
+    fix?: boolean;
+    format?: "biome";
+}
+/** /pt check 输出结果（供 shell 检查输出与是否 issues）。 */
+export interface CheckResult {
+    /** 格式化后的多行文本（biome 风格）。 */
+    output: string;
+    /** issue 数（errors + warnings）。 */
+    issueCount: number;
+    errors: number;
+    warnings: number;
+}
+/** /pt check 内核：从 session.assetHealthIssues（已扫）格式化输出。
+ *  v14.x（issue §Layer 3）：session_start 已扫，/pt check 直接格式化——不重复扫描。
+ *  未扫（null）→ 返回提示串 + 0 issue。
+ *
+ *  输出风格（biome/tsc 同源）：
+ *
+ *      ysl-developer.profile.md
+ *        × [error] ## 会话背景 缺 ### Modules
+ *           hint: 在 H2 段下加 `### Modules: [Scene, ...]`
+ *
+ *      × 6 errors, 0 warnings
+ *        hint: 运行 `/pt check --fix` 自动应用已知 migration
+ *
+ *  --profile X：只列该 profile 的 issue；其它 profile 的忽略（v1 简化）。
+ */
+export declare function checkText(session: SessionState, opts?: CheckOptions): CheckResult;

package/dist/commands.js

@@ -0,0 +1,344 @@
+// src/commands.ts — pt 命令纯函数内核（v10.x：command + tool 双注册架构）
+//
+// 设计动机（.pt/docs/designs/pt-command-tool-dual-registration.md）：
+//   - 人类（command） + LLM（tool）共享同一组纯函数内核，零逻辑重复
+//   - command 壳：ctx.ui.notify 呈现（src/index.ts）
+//   - tool 壳：return { content: [{ text }] } 呈现（src/index.ts）
+//   - 纪律：内核不依赖 ExtensionAPI / ExtensionCommandContext，只读 session + 调内部模块
+//
+// v12.x（issue pt-session-singleton-pi-web-pollution 修复）：
+//   - 内核函数签名加 `session: SessionState` 参数，调用方传 per-session state
+//   - 不再 import module-level `session` 单例（已删除）
+//
+// v14.x（issue pt-asset-migration-visibility Layer 3）：
+//   - 加 checkText() 内核 + CheckOptions：/pt check + pt_check tool 共享
+//   - 同步格式化 6 列 biome/tsc 风格 + hint/fix 展示
+import { join } from "node:path";
+import { MANUAL_DIR, MOD_FLOWS } from "./constants.js";
+import { bindFlowTemplate, findFlowInBlueprint } from "./render/turn-inject.js";
+import { filterDomainsByProfile } from "./schema.js";
+import { isFlowTemplateLike } from "./compile/type-guards.js";
+/** /pt status 内核：返回状态摘要文本（单行 | 分隔）。 */
+export function statusText(session) {
+    const flowCount = session.cachedBundles?.reduce((acc, b) => {
+        let n = 0;
+        // Phase term-P9.2：FlowTemplate 在 ## Flows 段（不再是 ## Manual）。仍只看 workflow 类型 Domain。
+        for (const d of b.domains) {
+            const flows = d.modules[MOD_FLOWS];
+            if (Array.isArray(flows))
+                n += flows.length;
+        }
+        return acc + n;
+    }, 0) ?? 0;
+    const domainCount = session.cachedBundles?.reduce((acc, b) => acc + b.domains.length, 0) ?? 0;
+    const blueprintCount = session.cachedBundles?.reduce((acc, b) => acc + b.blueprints.length, 0) ?? 0;
+    const profileCount = session.cachedBundles?.reduce((acc, b) => acc + b.profiles.length, 0) ?? 0;
+    // v14.x（issue pt-asset-migration-visibility Layer 2）：暴露 session_start 健康扫描结果
+    const healthIssues = session.assetHealthIssues;
+    const healthLine = healthIssues === null
+        ? "pt health: (not scanned)"
+        : healthIssues.length === 0
+            ? "pt health: ok"
+            : `pt health: ${healthIssues.length} issue${healthIssues.length > 1 ? "s" : ""} (${healthIssues.filter((i) => i.severity === "error").length} errors, ${healthIssues.filter((i) => i.severity === "warning").length} warnings)`;
+    // v15.x PR1（§6.7.6）：暴露 session_start pack 校验结果——每个 pack ✅ / ⚠ DEGRADED + 原因。
+    // pack 健康区别于 healthLine 的 profile 配置体检：pack 健康是"加载层健康"，profile 健康是"资产内容健康"。
+    const packValidation = session.packValidation;
+    const packLine = formatPackHealthLine(packValidation);
+    // v14.x（tagline）：statusText 显式展开 tagline（不受 footer 35 字符限制）
+    const tagline = session.cachedProfile?.tagline;
+    const taglineLine = tagline ? `pt tagline: ${tagline}` : "pt tagline: (none)";
+    return [
+        `pt profile: ${session.activeProfile ?? "(未激活)"}`,
+        `pt loadedFrom: ${session.loadedFrom ?? "(none)"}`, // v10.x：可观测性（issue pt-context-persist-lost）
+        `pt agent: ${session.activeAdapter?.name ?? "(none)"}`,
+        taglineLine,
+        `pt domains: ${domainCount}, blueprints: ${blueprintCount}, profiles: ${profileCount}, flows: ${flowCount}`,
+        `pt segment length: ${session.cachedSegment?.length ?? 0} chars`,
+        `pt cache hit: ${session.lastCacheHit ? "yes" : "no"}`,
+        `pt last built prompt: ${session.lastBuiltPrompt ? `${session.lastBuiltPrompt.length} chars` : "(未跑过 turn)"}`,
+        // issue pt-status-no-injection-state：暴露 4 态自报状态
+        `pt state: ${session.injectionState}${session.injectionError ? `: ${session.injectionError.slice(0, 40)}` : ""}`,
+        healthLine,
+        packLine,
+        `pt cwd: ${session.lastCwd}`,
+    ].join(" | ");
+}
+/** v15.x PR1（§6.7.6）— /pt status 暴露 pack 健康。
+ *  单行格式：`pt packs: N/M ok | [@prj] ✅ | [@gbl] ✅ | [@pt] ✅`
+ *  降级时附加原因：`[@prj] ⚠ DEGRADED — <errors[0].msg 截断 60 字符>`。
+ *  packValidation=null → `pt packs: (not validated)`（尚未 session_start）。
+ *  packValidation=[] → `pt packs: (none loaded)`（不应出现——session_start 总构造 3 个 pack）。 */
+function formatPackHealthLine(packValidation) {
+    if (packValidation === null)
+        return "pt packs: (not validated)";
+    if (packValidation.length === 0)
+        return "pt packs: (none loaded)";
+    const items = packValidation.map((r) => {
+        // v15.x §4.4.4（缺口 4）：reserved 显位置别名（reservedAlias），非 reserved 显 pack（manifest.name）
+        // 砍 desc——pack 详情走 /pt packs（缺口 5）
+        const label = r.reservedAlias ?? r.pack;
+        const version = r.version ? ` v${r.version}` : "";
+        if (r.ok) {
+            return `[@${label}]${version} ✅`;
+        }
+        const reason = r.errors[0]?.msg ?? "unknown";
+        return `[@${label}]${version} ⚠ DEGRADED — ${truncate(reason, 60)}`;
+    });
+    const okCount = packValidation.filter((r) => r.ok).length;
+    const summary = okCount === packValidation.length
+        ? `${okCount}/${packValidation.length} ok`
+        : `${okCount}/${packValidation.length} degraded`;
+    return `pt packs: ${summary} | ${items.join(" | ")}`;
+}
+/** v15.x PR2（§6.7.6）：description / error msg 截断辅助——单行 status 不被撑爆。 */
+function truncate(s, max) {
+    return s.length > max ? `${s.slice(0, max - 3)}...` : s;
+}
+/** v15.x §4.4.4（缺口 5）：/pt packs 详情命令——pack 诊断信息落点。
+ *  pack.name/version/desc/asset 计数走这里，status 单行不再塞 desc。
+ *  asset 计数：从 active bundle 的 workingSet.identity 索引按 pack.name 前缀过滤。 */
+export function packsText(session) {
+    const pv = session.packValidation;
+    if (!pv || pv.length === 0) {
+        return "pt packs: (none loaded)";
+    }
+    const bundle = session.cachedBundles?.[0];
+    const ws = bundle?.workingSet;
+    const lines = [`pt packs (${pv.length} loaded):`];
+    for (const r of pv) {
+        // v15.x §4.4.4（缺口 4）：reserved 显位置别名，settings 显 pack 名
+        const label = r.reservedAlias ?? r.pack;
+        const status = r.ok ? "✅" : "⚠ DEGRADED";
+        lines.push(`  [@${label}] v${r.version} ${status} (${r.source})`);
+        // reserved 退化场景：pack.name=位置别名，不显 name 行
+        if (r.pack !== label) {
+            lines.push(`    name: ${r.pack}`);
+        }
+        if (r.description) {
+            lines.push(`    ${r.description}`);
+        }
+        // asset 计数（从 workingSet.identity 按 pack.name 前缀统计）
+        if (ws) {
+            const prefix = `${r.pack}/`;
+            const domains = countByPrefix(ws.domains.identity, prefix);
+            const blueprints = countByPrefix(ws.blueprints.identity, prefix);
+            const profiles = countByPrefix(ws.profiles.identity, prefix);
+            lines.push(`    ${domains} domains, ${blueprints} blueprints, ${profiles} profiles`);
+        }
+    }
+    return lines.join("\n");
+}
+/** 按 key 前缀计数（§4.4.4 packsText 辅助）。 */
+function countByPrefix(map, prefix) {
+    if (typeof prefix !== "string")
+        return 0;
+    let n = 0;
+    for (const k of map.keys()) {
+        if (typeof k === "string" && k.startsWith(prefix))
+            n++;
+    }
+    return n;
+}
+/** /pt flows 内核：返回可用手册列表文本。无激活 Profile 返回提示串。
+ *
+ * v13.x（issue pt-turn-inject-not-profile-scoped）：不再预过滤——传全集 domains 给 listManuals，
+ * adapter 内部用 setAgentContext 时存下的 profile 自行 filterDomainsByProfile 过滤。 */
+export function flowsText(session) {
+    if (!session.cachedBundles || session.cachedBundles.length === 0 || !session.activeAdapter) {
+        return "无激活 Profile，先用 /pt-profile <name> 激活";
+    }
+    if (!session.cachedAgentContext || !session.cachedBlueprint) {
+        return "无激活 Profile，先用 /pt-profile <name> 激活";
+    }
+    const flows = session.activeAdapter.listManuals?.(session.cachedAgentContext, session.cachedBlueprint, session.cachedBundles[0].domains) ?? [];
+    if (flows.length === 0) {
+        return "当前 Profile 无可触发手册（turn 聚合组无含 Flows 段的 Domain）";
+    }
+    const lines = flows.map((f) => `  ${f.name} ${f.hint ?? ""}  ← ${f.domain}`);
+    return `可用手册（输入 /手册名 参数 或 /manual:<domain-name> 触发 Turn Inject）:\n${lines.join("\n")}`;
+}
+/** /pt full 内核：构建写入 .pt/cache/fulls/ 的完整 systemPrompt 字符串（v10.x 修复 pt-full-duplicate-segment）。
+ *
+ * 设计动机：消除 `/pt full` 与 PiAdapter `before_agent_start` 的双重拼接路径——
+ *   - PiAdapter 每轮把 segment 拼到 base，写回 `agent.state.systemPrompt`（= `ctx.getSystemPrompt()`）
+ *   - 第一轮 prompt 之后，`ctx.getSystemPrompt()` 已含 segment；旧版 `/pt full` 再拼一次 → 2× 重复
+ *   - 根因：两份拼接实现通过隐式时序耦合，缺乏单一信息源
+ *
+ * 修复：把 `lastBuiltPrompt`（由 PiAdapter 的 `onInjected` 回调写入，正是 LLM 实际看到的 systemPrompt）
+ *   作为 canonical source。第一轮之前的 fallback：模拟下一次 LLM 会看到的注入（保留旧版语义）。
+ *
+ * 边界纪律：
+ *   - 不动 PiAdapter（PiAdapter 行为正确，不重复注入）
+ *   - 不动 Pi 上游 API（`getSystemPrompt` 语义不变）
+ *   - 只动这一个函数体，外加调用方 `src/index.ts`
+ */
+export function buildFullPrompt(baseSystemPrompt, cachedSegment, lastBuiltPrompt) {
+    if (lastBuiltPrompt !== null) {
+        // 第一轮 prompt 之后：canonical source（= LLM 实际收到的 systemPrompt）
+        return lastBuiltPrompt;
+    }
+    if (cachedSegment) {
+        // 第一轮之前：模拟下一次 LLM 会看到的注入
+        return `${baseSystemPrompt}\n\n## 当前任务上下文\n\n${cachedSegment}`;
+    }
+    // 无 cachedSegment（未加载 Profile）
+    return baseSystemPrompt;
+}
+export function buildManualDoc(cwd, session, procedure, args) {
+    if (!procedure) {
+        return { content: "", filePath: "", error: "用法: /pt manual <procedure-name> [args...]" };
+    }
+    if (!session.cachedBundles || session.cachedBundles.length === 0 || !session.cachedBlueprint) {
+        return { content: "", filePath: "", error: "无激活 Profile，先用 /pt-profile <name> 激活" };
+    }
+    // v13.x（issue pt-turn-inject-not-profile-scoped）：按 Profile scope 过滤 + 传 profile
+    //   让 /pt manual 在未引用该 domain 的 Profile 下找不到手册（与 /pt flows 一致）
+    const scoped = filterDomainsByProfile(session.cachedBundles[0].domains, session.cachedProfile);
+    const tpl = findFlowInBlueprint(session.cachedBlueprint, scoped, procedure, session.cachedProfile);
+    if (!tpl) {
+        return {
+            content: "",
+            filePath: "",
+            error: `未找到手册: ${procedure}（用 /pt flows 查可用手册）`,
+        };
+    }
+    const bound = bindFlowTemplate(tpl, args);
+    const domainName = session.cachedBundles[0].domains.find((d) => {
+        // Phase term-P9.2：FlowTemplate 存 ## Flows 段（不是 ## Manual）。
+        const flows = d.modules[MOD_FLOWS];
+        return (Array.isArray(flows) &&
+            flows.some((t) => isFlowTemplateLike(t) && t.name === procedure));
+    })?.name ?? "";
+    const now = new Date().toISOString();
+    const ts = Date.now();
+    const lines = [];
+    lines.push("---");
+    lines.push(`procedure: ${procedure}`);
+    lines.push(`domain: ${domainName}`);
+    lines.push(`created: ${now}`);
+    lines.push("status: in-progress");
+    lines.push(`args: ${args || "(无)"}`);
+    lines.push("---");
+    lines.push("");
+    lines.push(`# ${procedure} 实例`);
+    lines.push("");
+    const boundLines = bound.split("\n");
+    let stepCount = 0;
+    for (const line of boundLines) {
+        if (line.startsWith("#"))
+            continue;
+        if (line.startsWith("_"))
+            continue;
+        const stepMatch = line.match(/^(\d+)\.\s+(.*)$/);
+        if (stepMatch) {
+            stepCount++;
+            lines.push(`- [ ] ${stepMatch[2]}`);
+            continue;
+        }
+        // observe 行（bindFlowTemplate 渲染的 "   - 验证参照：xxx"）→ checklist 子项
+        if (line.includes("验证参照：")) {
+            lines.push(`  ${line.trim()}`);
+            continue;
+        }
+        lines.push(line);
+    }
+    lines.push("");
+    lines.push("## 执行状态");
+    lines.push("| Step | Outcome | Message |");
+    lines.push("|---|---|---|");
+    for (let i = 1; i <= stepCount; i++) {
+        lines.push(`| ${i} | — | |`);
+    }
+    lines.push("");
+    lines.push("## 产物");
+    lines.push("<!-- 执行后用 edit 在此追加：路径 + 动作(created/modified) + 日期 -->");
+    lines.push("");
+    lines.push("## 更新指引");
+    lines.push("执行完每个 step 后：用 edit 把对应 `- [ ]` 改成 `- [x]`。");
+    lines.push("验证后：用 edit 把 ## 执行状态表 对应行的 `—` 改为 COMPLETED / DEVIATED / INCONCLUSIVE + Message。");
+    lines.push("全部完成后：用 edit 在 ## 产物 下追加创建/修改的文件路径（每行一条）。");
+    lines.push("status 全部完成后可改为 completed。");
+    const content = lines.join("\n");
+    const filePath = join(cwd, MANUAL_DIR, `${procedure}-${ts}.md`);
+    return { content, filePath };
+}
+/** /pt check 内核：从 session.assetHealthIssues（已扫）格式化输出。
+ *  v14.x（issue §Layer 3）：session_start 已扫，/pt check 直接格式化——不重复扫描。
+ *  未扫（null）→ 返回提示串 + 0 issue。
+ *
+ *  输出风格（biome/tsc 同源）：
+ *
+ *      ysl-developer.profile.md
+ *        × [error] ## 会话背景 缺 ### Modules
+ *           hint: 在 H2 段下加 `### Modules: [Scene, ...]`
+ *
+ *      × 6 errors, 0 warnings
+ *        hint: 运行 `/pt check --fix` 自动应用已知 migration
+ *
+ *  --profile X：只列该 profile 的 issue；其它 profile 的忽略（v1 简化）。
+ */
+export function checkText(session, opts = {}) {
+    const allIssues = session.assetHealthIssues;
+    if (allIssues === null) {
+        return {
+            output: "未扫描。重启 session 或运行 scanProjectHealth。",
+            issueCount: 0,
+            errors: 0,
+            warnings: 0,
+        };
+    }
+    // 过滤
+    let issues;
+    if (opts.profileName) {
+        issues = allIssues.filter((i) => i.name === opts.profileName);
+    }
+    else {
+        issues = allIssues;
+    }
+    if (issues.length === 0) {
+        const okMsg = opts.profileName
+            ? `✓ Profile「${opts.profileName}」配置正常`
+            : "✓ 项目所有 Profile 配置正常";
+        return { output: okMsg, issueCount: 0, errors: 0, warnings: 0 };
+    }
+    // 按 profile 分组（biome 风格：file → issues 列表）
+    const byProfile = new Map();
+    for (const i of issues) {
+        const arr = byProfile.get(i.name) ?? [];
+        arr.push(i);
+        byProfile.set(i.name, arr);
+    }
+    const lines = [];
+    for (const [profileName, profIssues] of byProfile) {
+        lines.push(`${profileName}.profile.md`);
+        for (const i of profIssues) {
+            const mark = i.severity === "error" ? "×" : "⚠";
+            const sev = i.severity === "error" ? "error" : "warning";
+            const where = i.field ? ` ${i.field}` : "";
+            lines.push(`  ${mark} [${sev}]${where} ${i.msg}`);
+            if (i.hint)
+                lines.push(`     hint: ${i.hint}`);
+            if (i.fix && !opts.fix)
+                lines.push(`     fix:  ${i.fix}`);
+        }
+        lines.push("");
+    }
+    // trim trailing blank
+    if (lines.length > 0 && lines[lines.length - 1] === "")
+        lines.pop();
+    // summary
+    const errorCount = issues.filter((i) => i.severity === "error").length;
+    const warningCount = issues.filter((i) => i.severity === "warning").length;
+    lines.push("");
+    lines.push(`× ${errorCount} error${errorCount > 1 ? "s" : ""}, ${warningCount} warning${warningCount > 1 ? "s" : ""}`);
+    lines.push(`  hint: 查看 .pt/docs/migrations/v9.0-to-v9.1-modules.md 修复指南`);
+    if (errorCount > 0 && !opts.fix) {
+        lines.push(`  hint: 运行 \`/pt check --fix\` 自动应用已知 migration（v2 范围）`);
+    }
+    return {
+        output: lines.join("\n"),
+        issueCount: issues.length,
+        errors: errorCount,
+        warnings: warningCount,
+    };
+}