@istuen/pt 0.1.1 → 0.1.2

package/dist/asset-pack/manifest.d.ts

@@ -1,3 +1,4 @@
+import type { PackSource } from "../schema.js";
 /** manifest 解析结果。ok=false 表示文件不存在/解析失败/校验不过——调用方走默认值。 */
 export interface ParsedManifest {
     /** 文件存在且 YAML 解析成功（name/version/description 校验失败仍 ok=true，错误进 warnings）。 */
@@ -18,6 +19,10 @@ export interface ParsedManifest {
  * - name 非 kebab-case / 保留名冲突 → warnings + name 丢弃（走 basename）
  * - version 非 semver → warnings + version 丢弃（走 "0.0.0"）
  *
+ * v15.x builtin 特例：source="builtin" 时 manifest.name 等于保留名合法
+ * （位置 alias @pt = 身份 alias 合一；builtin pack 的"身份"就是"内置"）。
+ * project/global/settings pack 仍禁用保留名（保护位置 slot）。
+ *
  * 永远不抛异常（§2.2 校验规则：解析失败当无 manifest 处理，不阻断加载）。
  */
-export declare function parseManifest(rootDir: string): Promise<ParsedManifest>;
+export declare function parseManifest(rootDir: string, source?: PackSource): Promise<ParsedManifest>;

package/dist/asset-pack/manifest.js

@@ -36,9 +36,13 @@ const KEBAB_RE = /^[a-z0-9-]{1,64}$/;
  * - name 非 kebab-case / 保留名冲突 → warnings + name 丢弃（走 basename）
  * - version 非 semver → warnings + version 丢弃（走 "0.0.0"）
  *
+ * v15.x builtin 特例：source="builtin" 时 manifest.name 等于保留名合法
+ * （位置 alias @pt = 身份 alias 合一；builtin pack 的"身份"就是"内置"）。
+ * project/global/settings pack 仍禁用保留名（保护位置 slot）。
+ *
  * 永远不抛异常（§2.2 校验规则：解析失败当无 manifest 处理，不阻断加载）。
  */
-export async function parseManifest(rootDir) {
+export async function parseManifest(rootDir, source) {
     const file = join(rootDir, "pt-asset-pack.yaml");
     let raw;
     try {
@@ -66,10 +70,13 @@ export async function parseManifest(rootDir) {
     if (typeof data.name === "string" && data.name.trim()) {
         const n = data.name.trim();
         if (!KEBAB_RE.test(n)) {
-            warnings.push(`manifest.name "${n}" not kebab-case, falling back to basename`);
+            warnings.push(`[repair-required][name-kebab] manifest.name "${n}" not kebab-case, fallback: basename. Auto-fix: /manual:pack-management#pack-repair`);
         }
-        else if (RESERVED_NAMES.has(n)) {
-            warnings.push(`manifest.name "${n}" is reserved, falling back to basename`);
+        else if (RESERVED_NAMES.has(n) && source !== "builtin") {
+            // v15.x builtin 特例：source="builtin" 时保留名（prj/gbl/pt）合法——位置 alias = 身份 alias 合一。
+            // 其他 source（project/global/settings）仍禁用保留名：位置 slot 是 reserved pack 的，身份 alias
+            // 不能占用。project pack 应该用跨项目身份名（如 pt-internal）走身份寻址，不是用保留名。
+            warnings.push(`[repair-required][name-reserved] manifest.name "${n}" is reserved, fallback: basename. Auto-fix: /manual:pack-management#pack-repair`);
         }
         else {
             name = n;
@@ -79,7 +86,7 @@ export async function parseManifest(rootDir) {
     if (typeof data.version === "string" && data.version.trim()) {
         const v = data.version.trim();
         if (!SEMVER_RE.test(v)) {
-            warnings.push(`manifest.version "${v}" not semver, treating as "0.0.0"`);
+            warnings.push(`[repair-required][version-semver] manifest.version "${v}" not semver, default: "0.0.0". Auto-fix: /manual:pack-management#pack-repair`);
         }
         else {
             version = v;

package/dist/asset-pack/md-file-pack.js

@@ -65,11 +65,25 @@ export class MdFilePack {
      *  - reserved pack 无 manifest → 退化到 RESERVED_FALLBACK_NAME.get(source)
      *  - 非 reserved pack 无 manifest → basename 兜底 */
     static async create(args) {
-        const manifest = await parseManifest(args.rootDir);
+        const manifest = await parseManifest(args.rootDir, args.source);
         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");
+        if (args.adapterCtx?.notify) {
+            if (manifest.warnings.length > 0) {
+                // 检测 [repair-required] 前缀的 warnings——加 manual hint 引导 LLM 调 /manual:pack-management
+                const hasRepairRequired = manifest.warnings.some((w) => w.startsWith("[repair-required]"));
+                const manualHint = hasRepairRequired
+                    ? "\n→ 调 /manual:pack-management 让 LLM 自动修复"
+                    : "";
+                args.adapterCtx.notify(`Pt: pack "${dirName}" manifest 警告：${manifest.warnings.join("; ")}${manualHint}`, "warning");
+            }
+            else if (!manifest.ok && args.source === "settings") {
+                // v15.x §2.4.2 + pack-naming：reserved pack（project/global/builtin）无 manifest 是
+                // back-compat 退化路径（退到位置别名 prj/gbl/pt），设计预期——silent。
+                // 只有 settings pack（用户主动声明）无 manifest 时才通知：basename 兜底"易碎"，
+                // 建议加 pt-asset-pack.yaml 让 pack 成为自描述实体，/manual:pack-management#pack-create。
+                args.adapterCtx.notify(`Pt: pack "${dirName}" 无 manifest（basename 兜底）— 建议添加 pt-asset-pack.yaml 让 pack 成为自描述实体。/manual:pack-management#pack-create`, "warning");
+            }
         }
         // name 解析优先级（§2.4.2）：
         //   1. manifest.name（身份 alias 优先）

package/dist/builtin/assets/domains/pack-management.md

@@ -0,0 +1,170 @@
+---
+name: pack-management
+---
+
+# pack-management
+
+Pack 全生命周期管理 domain——创建 / 调整 / 迭代 / 迁移 / 修复。builtin profile
+`guide` 引用本 domain，用户 `/manual:pack-management` 触发任意 FlowTemplate，
+LLM 跟着 Scene + Rules + Flow + Checklist 走即可。
+
+**核心立场**：manifest 是 pack 的**身份证 + 说明书**——没有 manifest 的目录只是
+back-compat 兜底状态（参见 `pt-pack-location-vs-identity-alias`），不是真正的
+pt pack。缺 manifest / 写错时，跟着 `pack-repair` flow 走即可自描述修复。
+
+## Scene
+
+### pack-lifecycle
+- desc: Pack 五态——创建（init）→ 迭代（add/change asset）→ 迁移（schema 升级）→ 废弃（deprecate）→ 修复（manifest 缺失/错误回退到创建态）。每态对应一个 FlowTemplate。
+
+### pack-structure
+- desc: Pt pack 标准目录结构——必须含 `domains/` + `blueprints/` + `profiles/` 三个子目录之**一**（至少一个）；可选 `pt-asset-pack.yaml` manifest（**强烈建议始终提供**——manifest 是身份证，不是装饰）
+
+### 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 包发布）。每类走相同 MdFilePack 管线，差别只在入口函数和 name fallback 表。
+
+### pack-manifest
+- desc: `pt-asset-pack.yaml` 是 pack 自描述 manifest——三个字段：`name`（kebab-case 身份 alias，跨项目寻址用）/ `version`（semver，缓存失效标识）/ `description`（人类可读说明，UI 展示用）。字段全部可选——但**强烈建议始终提供**（back-compat fallback 是过渡方案）。
+
+### validation-codes
+- desc: validatePack 返回的错误码——`dir-not-found`（路径不存在）/ `no-asset-subdir`（无 asset 子目录）/ `load-failed`（加载抛异常）/ `manifest-warnings`（manifest 缺失/解析失败/字段校验失败，**不阻断**但会走 notify + manual hint）
+
+### pack-naming
+- desc: 寻址双层语义——位置 alias（`@prj`/`@gbl`/`@pt`，固定 3 slot 物理位置指针，reserved pack 用）+ 身份 alias（`@<manifest-name>`，跨项目寻址用，settings pack 用）。manifest.name 走身份 alias，无 manifest 时 reserved pack 退到位置 alias，settings pack 退到 basename（**易碎**，建议始终提供 manifest）。
+
+### pack-reserved-vs-external
+- desc: Pt Pack 体系按"是否有固定位置约定"分两类——
+
+  **① 固定位置 slot（reserved，3 个 slot，本质是位置约定）**：
+  - `@prj` → 项目 cwd 下的 `.pt/assets/`（项目 pack）
+  - `@gbl` → 用户 home 下的 `~/.pt/assets/`（用户私有通用 pack）
+  - `@pt`  → npm 包内嵌 `src/builtin/assets/`（工具内嵌 pack）
+
+  三者都是"外部 pack"——它们不在 pt 工具代码本身里，是用户在文件系统 / npm 包里的资产。reserved 不是因为"内置"，而是因为**有固定的物理位置约定**——pt 工具预先知道去哪里找它们，不用用户声明路径。
+
+  **② 用户/外部 Pt Packs（settings，通过 manifest.name 走身份 alias）**：
+  - 用户主动声明在 `.pi/settings.json` 的 `pt.asset-packs[]` 中
+  - 身份由 manifest.name 决定（自由命名，避开保留名）
+  - 没有固定位置约定——可以是任意路径、任意名字
+  - 包含第三方 pack（团队 / 公司 / 社区发布的）
+
+  **关键区别**：① 有固定位置（物理约定）→ 工具自己找；② 有固定身份（manifest.name）→ 用户声明路径找。
+
+### pack-builtin-special
+- desc: `@pt` 是最特殊的 reserved pack——位置 alias + 身份 alias 合一。
+
+  - builtin pack 的"身份"就是"内置"，**不需要跨项目身份寻址**（位置固定 = `pt`）
+  - 位置 slot `@pt` 已经是其完整身份表达
+  - manifest.name="pt" 合法（保留名作为身份 alias）——位置 alias = 身份 alias 合一
+  - working set 双索引 key 重合：`@pt/foo` 的 location 和 identity entry 指向同一份 asset
+  - 其他 reserved pack（prj/gbl）不享受合一——项目/全局 pack 仍用跨项目身份名（`pt-internal` 等）
+
+  设计动机：v10.x 时期 builtin pack.name="pt"（位置别名退化）是 back-compat 默认行为；本轮修复把这个行为**显式声明**为设计意图，而不是引入 `pt-builtin` 之类冗余名字。保留名规则对 builtin 特例放行（`parseManifest(rootDir, "builtin")`），project/global/settings pack 仍禁用保留名。
+
+## Flows
+
+### pack-create
+- argument-hint: <pack-root>
+- intent: 从零创建新 pack——创建目录结构 + 写 `pt-asset-pack.yaml` 模板（name 走 kebab-case 提示用户输入，version 默认 `0.1.0`）
+- vars: [pack-root]
+- step: 确认 pack-root 不存在或为空（避免覆盖现有 pack）
+- step: `mkdir -p <pack-root>/{domains,blueprints,profiles}`
+- step: 写 `<pack-root>/pt-asset-pack.yaml` 模板：
+- step:   ```yaml
+  name: <kebab-case-name>   # 跨项目身份 alias
+  version: 0.1.0            # semver
+  description: <一句话说明>
+  ```
+- step: 校验：name 满足 `[a-z0-9-]{1,64}` 且非保留字（prj/gbl/pt/project/global/builtin）
+- step: 校验：version 满足 `^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$`
+- step: 若作为 settings pack 暴露：在 `.pi/settings.json` 加 `pt.asset-packs: [{ "path": "<pack-root>" }]`
+- step: 验证：`/pt status` → 新 pack 显示在 Pack 健康行
+
+### pack-repair
+- argument-hint: (无)
+- intent: Manifest 缺失/错误时自描述修复——按错误码分类处置后重启 session 验证
+- vars: []
+- step: `/pt status` 查看 pack 健康状态 + manifest warnings（如果有 `[repair-required]` 前缀，说明需要修复）
+- step: 按错误码分类处置：
+- step:   - manifest 缺失：走 `pack-create` flow 创建 `pt-asset-pack.yaml`（保留现有 assets 子目录）
+- step:   - manifest 解析失败：检查 YAML 语法（top-level 必须是 mapping）
+- step:   - name 非 kebab-case：改名满足 `[a-z0-9-]{1,64}`
+- step:   - name 是保留字：改用其他身份 alias（不能是 prj/gbl/pt/project/global/builtin）
+- step:   - version 非 semver：改成 `^\d+\.\d+\.\d+` 格式
+- step:   - dir-not-found：`mkdir -p <pack-root>/{domains,blueprints,profiles}`
+- step:   - no-asset-subdir：至少创建一个 asset 子目录
+- step:   - load-failed：检查资产文件格式（`.md` frontmatter 合法 / `.blueprint.yaml` 语法正确）
+- step: 修复后重启 pi session（`projectPackDegraded` 在 session_start 重新校验时清零）
+- step: `/pt status` 确认 pack 健康（✅，无 `[repair-required]` warnings）
+
+### pack-iterate
+- argument-hint: <pack-root>
+- intent: Pack 内容迭代——添加 / 修改 / 删除 asset，并按需 bump version
+- vars: [pack-root]
+- step: 修改 asset 文件（`domains/*.md` / `blueprints/*.blueprint.yaml` / `profiles/*.profile.md`）
+- step: 资产改动后删 `.pt/cache/agent-contexts/*.agent-context.md`（强制重编译，sourceHash 自动失效）
+- step: 修改 manifest.version——breaking change 升 major，向后兼容加 feature 升 minor，bug fix 升 patch
+- step: 同步 description（如果 pack 用途变化）
+- step: 验证：`/pt status` → pack version 已更新 → 跑 `npm run verify` 全测试通过
+
+### pack-migrate
+- argument-hint: <pack-root>
+- intent: Pt schema 升级时 pack 内容迁移——按迁移指南更新 asset 格式
+- vars: [pack-root]
+- step: 读迁移指南（`.pt/docs/migrations/<from>-to-<to>-*.md` 或 `/manual:pt-asset-migration`）
+- step: 按指南转换每个 asset 文件（如 v9.0 → v9.1 modules-to-profile-complete：Blueprint `modules` 字段删除，迁到 Profile `### Modules`）
+- step: 跑 `pt_check` LLM 工具检查 pack 健康（missing-modules / dangling-blueprint-ref / empty-segment / orphan-h2 等）
+- step: 修完所有报错后 bump version（breaking change 升 major）
+- step: 验证：`/pt status` 健康 + `npm run verify` 通过
+
+## Rules
+
+### manifest-required-as-identity
+- check: Pack 必须有 `pt-asset-pack.yaml` manifest——没有 manifest 的目录只是 back-compat 兜底状态（reserved pack 退到 prj/gbl/pt，settings pack 退到 basename）。Manifest 是 pack 的身份证 + 说明书，缺它 pack 不是真正的 pt pack
+
+### manifest-name-kebab-case
+- check: `manifest.name` 必须满足 `[a-z0-9-]{1,64}`——kebab-case 格式，1-64 字符。校验失败 → warning + fallback 到 basename（settings pack）或位置 alias（reserved pack）
+
+### manifest-name-not-reserved
+- check: `manifest.name` 不能等于保留字——`prj`/`gbl`/`pt`/`project`/`global`/`builtin` 全部禁用（reserved pack 位置 alias 专用）。冲突 → warning + fallback
+
+### manifest-version-semver
+- check: `manifest.version` 必须满足 `^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$`——semver 格式。校验失败 → warning + 默认 "0.0.0"
+
+### manifest-fallback-is-transitional
+- check: Manifest 缺失时的 fallback 是**过渡方案**，不是设计意图——reserved pack 退到位置 alias、settings pack 退到 basename 都是 back-compat 妥协。Pack 作者应始终提供 manifest，让 pack 成为自描述实体
+
+### reserved-pack-position-agreement
+- check: Reserved pack（`@prj` / `@gbl` / `@pt`）的"reserved"**不是"内置"**——三者都是"外部 pack"（项目 / 用户 home / npm 包里的资产），reserved 是因为有**固定的物理位置约定**（pt 工具预先知道去哪里找）。用户资产 / 第三方 pack 走 settings，通过 manifest.name 走身份 alias（见 `pack-reserved-vs-external`）
+
+### builtin-pack-name-merges-position-and-identity
+- check: builtin pack 是 3 个 reserved slot 里最特殊的——位置 alias `@pt` = 身份 alias `@pt` 合一。`src/builtin/assets/pt-asset-pack.yaml` 的 `name: pt` 合法（保留名作为身份 alias），working set 双索引 key 重合。其他 reserved pack（prj/gbl）仍用跨项目身份名（`pt-internal` 等），不合一（见 `pack-builtin-special`）
+
+### validate-pack-never-throws
+- check: validatePack 失败时返 `ValidationResult` 对象（`ok=false` + `errors[]`），不抛异常——保证加载链不阻断（§6.7.7）。Manifest parse 失败同样不阻断（parseManifest 已容错，warning 进 notify）
+
+### project-pack-degradation
+- check: Project pack 失效时强制激活 builtin `guide` profile（`projectPackDegraded=true`），覆盖用户配置的 `pt.default-profile`——保证 pi 可用让用户走 `pack-repair` flow 修复（§6.7.3）
+
+### restart-after-repair
+- check: 修复 pack 后必须重启 pi session——`projectPackDegraded` 标记在 session_start 重新校验时清零，不重启则继续降级
+
+### global-pack-guide-non-interactive
+- check: 全局 Pack 初始化引导仅在 TTY + 非 CI + 无 `PT_NO_GUIDE` 环境触发（§7.5.1）——避免阻塞 CI / 后台进程
+
+## Checklists
+
+### pack-create-checklist
+- step: pack-root 路径合法（绝对路径或相对 cwd）
+- step: pack-root 不存在或为空（避免覆盖）
+- step: 至少一个 asset 子目录存在（domains/blueprints/profiles）
+- step: `pt-asset-pack.yaml` 存在且字段合法（kebab-case name / semver version / description 可选）
+- step: 若作为 settings pack 暴露，`.pi/settings.json` 的 `pt.asset-packs[]` 已声明
+- step: `/pt status` 显示新 pack 健康（✅）
+
+### pack-repair-checklist
+- step: `/pt status` 列出所有 `[repair-required]` warnings
+- step: 每个 warning 对应 pack-repair flow 的一个 step（manifest 缺失 / 解析失败 / name 校验 / version 校验 / dir-not-found / no-asset-subdir / load-failed）
+- step: 修复后 `/pt status` 无 `[repair-required]` warnings
+- step: 重启 pi session 后 `projectPackDegraded` 标记清零
+- step: `npm run verify` 通过（除 phase9 fixture 错位独立 bug）

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

@@ -1,7 +1,7 @@
 ---
 name: guide
 blueprint: dev-knowledge
-domains: [user-info, agent-info, project-analysis, authoring, usage, pack-repair]
+domains: [user-info, agent-info, project-analysis, authoring, usage, pack-management]
 ---
 
 # guide (profile)

package/dist/builtin/assets/pt-asset-pack.yaml

@@ -0,0 +1,22 @@
+# pt-asset-pack.yaml — Pt builtin 资产（随 npm 包发布）
+#
+# 加载位置：src/builtin/assets/（builtin pack 根目录）
+# 加载方式：builtin pack（reserved）→ pack name 走 manifest.name="pt"。
+# 位置 alias @pt + 身份 alias @pt 合一（同一索引条目覆盖同一 key）。
+#
+# 设计意图（§2.4.2 + builtin 特例）：
+#   - builtin pack 的"身份"就是"内置"，位置 slot @pt 已是其完整身份表达
+#   - 不需要额外身份别名（如 pt-builtin）——跨项目身份寻址对 npm 内嵌 pack 无意义
+#   - 与 back-compat 默认行为一致（无 manifest 时 pack.name=位置别名）
+#   - 保留名规则对 builtin 特例放行（manifest.ts:name-validation）：builtin 允许用
+#     "prj/gbl/pt" 作 manifest.name；project/global/settings pack 仍禁用保留名
+#
+# 加 manifest 的好处（§2.4.2）：
+#   - /pt status 显示真实 version/description（不再永远 v0.0.0 / undefined）
+#   - 跨 builtin 的 manifest 校验走同一条 parseManifest 路径，无双轨
+#   - 与 project pack 的 manifest 校验语义对称（同样：reserved pack 读 manifest，
+#     身份 alias 优先；只是 builtin 的"身份"恰好等于位置别名）
+
+name: pt
+version: 0.0.0
+description: Pt builtin assets（随 npm 包发布，跨项目复用——guide profile + usage/authoring 等参考文档）

package/dist/index.js

@@ -21,7 +21,7 @@
 //   - `session_shutdown` 调 `clearSessionById(sessionId)` 精确清本 session
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
@@ -39,6 +39,7 @@ import { clearSessionById, getSessionById, resetSessionState, } from "./session.
 import { buildFullPrompt, buildManualDoc, checkText, flowsText, packsText, statusText, } from "./commands.js";
 import { loadAndTranspile } from "./transpile.js";
 import { persistManualToSession, refreshInjectionFooter, refreshManualWidget, tryRestoreManual, } from "./manual-session.js";
+import { writeProbeResult } from "./manual-writeback.js";
 import { slog } from "./slog.js";
 /** 从 ExtensionContext 拿 sessionId（tool / command handler ctx 形态）。 */
 function getSessionIdFromCtx(ctx) {
@@ -762,15 +763,40 @@ export default function (pi) {
                     : `? ${result.message}`;
             // v11.x：verify 后重读文件刷新 widget（用户可能手动 tick 了 checklist）
             // 不改 session.activeManual，只 refresh 派生数据（widget + cachedManualProgress）
+            // v15.x（issue pt-verify-result-not-written-back-to-manual）：自动写回 manual 文件
+            //   - 按 probe 名匹配 step 的 observe 列表，定位 ## 执行状态 对应行
+            //   - 写 outcome + message + 维护 frontmatter 注释的 completed probes 列表
+            //   - step 全部 observe 都 completed → checklist - [ ] → - [x]
+            //   - withFileMutationQueue 保证并发安全
+            //   - 写回失败不阻断 verify 结果返回（异常 catch 走 text 末尾提示）
             const sessionId = getSessionIdFromCtx(ctx);
             const s = sessionId ? getSessionById(sessionId) : null;
+            let writebackNote = "";
             if (s?.activeManual) {
+                const filePath = s.activeManual.filePath;
+                try {
+                    await withFileMutationQueue(filePath, async () => {
+                        const before = await readFile(filePath, "utf8");
+                        const wb = writeProbeResult(before, params.probe, result.outcome, result.message);
+                        if (wb.changed) {
+                            await writeFile(filePath, wb.content, "utf8");
+                            const checked = wb.checkedSteps.length > 0 ? `，勾选 ${wb.checkedSteps.length} 个 checklist` : "";
+                            writebackNote = `\n↳ 已写回 manual step ${wb.stepIndexes.join(", ")}${checked}`;
+                        }
+                        else if (wb.matchCount === 0) {
+                            writebackNote = `\n? probe "${params.probe}" 未匹配 activeManual 任何 step 的 observe（${filePath}）`;
+                        }
+                    });
+                }
+                catch (e) {
+                    writebackNote = `\n! 写回 manual 失败: ${errMsg(e)}`;
+                }
                 await refreshManualWidget(ctx.ui, s);
                 refreshInjectionFooter(ctx.ui, s);
             }
             return {
-                content: [{ type: "text", text }],
-                details: result,
+                content: [{ type: "text", text: text + writebackNote }],
+                details: { ...result, writeback: writebackNote || undefined },
             };
         },
     });

package/dist/manual-session.d.ts

@@ -10,9 +10,12 @@ declare function persistManualToSession(pi: ExtensionAPI, m: ActiveManual): void
 declare function refreshInjectionFooter(ui: ExtensionUIContext, session: SessionState): void;
 /** 刷新 widget（aboveEditor）。根据 session.activeManual 决定显示/撤掉。
  *  - 无 activeManual → 撤 widget
- *  - 文件不存在 / 已 completed → 清 activeManual + 撤 widget
+ *  - 文件不存在 / 真完成（status=completed + stepDone===stepTotal + 无 —/INCONCLUSIVE）→ 清 activeManual + 撤 widget
+ *  - 伪完成（status=completed 但 step 未全勾或有 —/INCONCLUSIVE）→ 仍渲染 widget，加 ⚠ fake done 提示
  *  - in-progress → 渲染 3 行 widget + 更新 cachedManualProgress（footer 同步读）
- *  v12.x：state 全部从 session 参数读，不再读写 module-level 单例。 */
+ *  v12.x：state 全部从 session 参数读，不再读写 module-level 单例。
+ *  v15.x（issue pt-manual-completion-check-too-loose）：用 checkManualCompletion 替代 `p.status === "completed"`,
+ *  让伪完成的 manual 仍 active（widget 重新挂载，提示用户步骤未全完成）。 */
 declare function refreshManualWidget(ui: ExtensionUIContext, session: SessionState): Promise<void>;
 /** session_start 时试恢复 manual：读 pt:active-manual entry → 校验文件存在 + status !== completed。
  *  独立于 profile 加载链——profile 失败 / 无 profile 也能恢复 manual 追踪。 */

package/dist/manual-session.js

@@ -21,7 +21,7 @@
 //   - profile-persist：MinimalSessionManager
 //   - slog：slog（session-scoped logger 快捷）
 //   - diagnostics：errMsg
-import { isManualActive, parseManualProgress, renderManualFooterSuffix, renderManualWidgetLines, } from "./manual-track.js";
+import { checkManualCompletion, isManualActive, parseManualProgress, renderManualFooterSuffix, renderManualWidgetLines, } from "./manual-track.js";
 import { renderInjectionFooter } from "./injection-status.js";
 import { errMsg } from "./diagnostics.js";
 import { slog } from "./slog.js";
@@ -94,9 +94,12 @@ function refreshInjectionFooter(ui, session) {
 }
 /** 刷新 widget（aboveEditor）。根据 session.activeManual 决定显示/撤掉。
  *  - 无 activeManual → 撤 widget
- *  - 文件不存在 / 已 completed → 清 activeManual + 撤 widget
+ *  - 文件不存在 / 真完成（status=completed + stepDone===stepTotal + 无 —/INCONCLUSIVE）→ 清 activeManual + 撤 widget
+ *  - 伪完成（status=completed 但 step 未全勾或有 —/INCONCLUSIVE）→ 仍渲染 widget，加 ⚠ fake done 提示
  *  - in-progress → 渲染 3 行 widget + 更新 cachedManualProgress（footer 同步读）
- *  v12.x：state 全部从 session 参数读，不再读写 module-level 单例。 */
+ *  v12.x：state 全部从 session 参数读，不再读写 module-level 单例。
+ *  v15.x（issue pt-manual-completion-check-too-loose）：用 checkManualCompletion 替代 `p.status === "completed"`,
+ *  让伪完成的 manual 仍 active（widget 重新挂载，提示用户步骤未全完成）。 */
 async function refreshManualWidget(ui, session) {
     const m = session.activeManual;
     if (!m) {
@@ -105,7 +108,7 @@ async function refreshManualWidget(ui, session) {
         return;
     }
     const p = await parseManualProgress(m.filePath);
-    if (!p || p.status === "completed") {
+    if (!p || !checkManualCompletion(p)) {
         session.activeManual = null;
         session.cachedManualProgress = null;
         ui.setWidget("pt-manual", undefined);

package/dist/manual-track.d.ts

@@ -1,14 +1,32 @@
+/** ## 执行状态 表的 Outcome 列规范化为 4 个值之一（其他字符串如 TODO 视为 INCONCLUSIVE）。
+ *  - "—"        ：未填写（buildManualDoc 表头初始值）
+ *  - "COMPLETED"：执行符合预期
+ *  - "DEVIATED" ：偏离预期（不是失败，见 src/schema.ts ProbeOutcomeKind 注释）
+ *  - "INCONCLUSIVE"：无法判定（人工评估 / probe 缺参数等） */
+export type OutcomeKind = "—" | "COMPLETED" | "DEVIATED" | "INCONCLUSIVE";
+/** Manual 实例文件 ## 执行状态 表的某一行（stepIndex + outcome）。
+ *  stepIndex 1-indexed（与表行 | N | ... 对齐）。 */
+export interface StepOutcome {
+    stepIndex: number;
+    outcome: OutcomeKind;
+}
 /** Manual 实例文件 parse 结果。
  *  - procedure：从 frontmatter.procedure 取
  *  - stepDone / stepTotal：实时正则数 "- [x]" / "- [ ]"
  *  - status：frontmatter.status（in-progress / completed）
- *  - nextStep：第一个 "- [ ]" 行去前缀的文本（下一步该做的），无则 null */
+ *  - nextStep：第一个 "- [ ]" 行去前缀的文本（下一步该做的），无则 null
+ *  - stepOutcomes：从 ## 执行状态 表抽的每步 outcome（长度 ≤ stepTotal，缺行视为未完成）
+ *  - hasUnfinishedOutcome：任一 outcome 是 "—" 或 "INCONCLUSIVE"（伪完成征兆之一）
+ *  - pseudoComplete：status=completed 但有伪完成征兆（stepDone < stepTotal 或 hasUnfinishedOutcome） */
 export interface ManualProgress {
     procedure: string;
     stepDone: number;
     stepTotal: number;
     status: string;
     nextStep: string | null;
+    stepOutcomes: StepOutcome[];
+    hasUnfinishedOutcome: boolean;
+    pseudoComplete: boolean;
 }
 /** 从 manual 实例文件 parse 进度。失败返回 null（容错，不抛）。 */
 export declare function parseManualProgress(filePath: string): Promise<ManualProgress | null>;
@@ -17,19 +35,33 @@ export declare function parseManualProgress(filePath: string): Promise<ManualPro
  *   1. frontmatter：取首段 `---` ... `---` 之间的 YAML
  *   2. procedure / status：从 frontmatter 行解析（`key: value` 形式，宽松）
  *   3. checklist：全文正则 `/^- \[([ x])\]\s+(.+)$/gm` 数 done / total
- *   4. nextStep：第一个未完成项的文本（去前缀） */
+ *   4. nextStep：第一个未完成项的文本（去前缀）
+ *   5. stepOutcomes：从 ## 执行状态 段抽 `| N | <outcome> | <message> |` 行
+ *   6. hasUnfinishedOutcome：任一 outcome 是 "—" 或 "INCONCLUSIVE"
+ *   7. pseudoComplete：status=completed 但 stepDone<stepTotal 或 hasUnfinishedOutcome */
 export declare function parseManualProgressFromContent(content: string): ManualProgress | null;
 /** widget 渲染：3 行 string[]，给 `ui.setWidget("pt-manual", lines, { placement: "aboveEditor" })` 用。
- *  - 第 1 行：`pt ▶ <procedure>  step <done>/<total>  (<status>)`（completed 加 ` ✓ done`）
+ *  - 第 1 行：`pt ▶ <procedure>  step <done>/<total>  (<status>)`（completed 加 ` ✓ done`；pseudoComplete 加 `⚠ fake done`）
  *  - 第 2 行：`  next: <nextStep 文本>`（无 nextStep 时该行省略）
  *  - 第 3 行：`  file: <filePath>`
- *  status === completed 时仍显示，但 footer 后缀改 done；widget 撤掉由 caller 决定（见 index.ts refreshManualWidget）。 */
+ *  status === completed 时仍显示，但 footer 后缀改 done；widget 撤掉由 caller 决定（见 index.ts refreshManualWidget）。
+ *  v15.x（issue pt-manual-completion-check-too-loose）：pseudoComplete 时加 ⚠ 提示用户
+ *  （status=completed 但 stepDone<stepTotal 或 hasUnfinishedOutcome → 伪完成）。 */
 export declare function renderManualWidgetLines(filePath: string, p: ManualProgress): string[];
 /** footer 后缀：有 activeManual 时追加。
  *  - in-progress → `· manual: <procedure> <done>/<total>`
- *  - completed   → `· manual: <procedure> done` */
+ *  - completed   → `· manual: <procedure> done`
+ *  - pseudoComplete（status=completed 但 stepDone<stepTotal 或 hasUnfinishedOutcome）→ `· manual: <procedure> ⚠ fake done` */
 export declare function renderManualFooterSuffix(p: ManualProgress): string;
-/** 文件存在 + status !== completed。配合 widget/footer 决定要不要展示。
+/** 检查 manual 实例是否应视为 active（widget 继续显示 + footer 显示）。
+ *  v15.x（issue pt-manual-completion-check-too-loose）：硬校验 status=completed 也需 step 全勾 + outcome 非 —/INCONCLUSIVE。
+ *  - status !== "completed" → true（active）
+ *  - status="completed" 但 stepDone < stepTotal → true（伪完成）
+ *  - status="completed" 但 hasUnfinishedOutcome → true（伪完成）
+ *  - status="completed" 且 stepDone === stepTotal 且无 —/INCONCLUSIVE → false（真完成） */
+export declare function checkManualCompletion(p: ManualProgress): boolean;
+/** 文件存在 + checkManualCompletion(p) === true。配合 widget/footer 决定要不要展示。
  *  - 用 fs.access 探测存在（轻量，不读全文）
- *  - 真的 parse status 用 parseManualProgress（一次 readFile 取齐） */
+ *  - 真的 parse status 用 parseManualProgress（一次 readFile 取齐）
+ *  v15.x：status=completed 时不再直接判 active，需 checkManualCompletion 硬校验 */
 export declare function isManualActive(filePath: string): Promise<boolean>;

package/dist/manual-track.js

@@ -22,12 +22,28 @@ export async function parseManualProgress(filePath) {
         return null;
     }
 }
+/** 规范化 Outcome 列字符串到 OutcomeKind。未识别值归 INCONCLUSIVE（保守按未完成处理）。 */
+function normalizeOutcome(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "—" || trimmed === "-" || trimmed === "")
+        return "—";
+    if (trimmed === "COMPLETED")
+        return "COMPLETED";
+    if (trimmed === "DEVIATED")
+        return "DEVIATED";
+    if (trimmed === "INCONCLUSIVE")
+        return "INCONCLUSIVE";
+    return "INCONCLUSIVE";
+}
 /** 内部：从字符串内容 parse（便于单测 & 未来内联输入）。
  *  算法：
  *   1. frontmatter：取首段 `---` ... `---` 之间的 YAML
  *   2. procedure / status：从 frontmatter 行解析（`key: value` 形式，宽松）
  *   3. checklist：全文正则 `/^- \[([ x])\]\s+(.+)$/gm` 数 done / total
- *   4. nextStep：第一个未完成项的文本（去前缀） */
+ *   4. nextStep：第一个未完成项的文本（去前缀）
+ *   5. stepOutcomes：从 ## 执行状态 段抽 `| N | <outcome> | <message> |` 行
+ *   6. hasUnfinishedOutcome：任一 outcome 是 "—" 或 "INCONCLUSIVE"
+ *   7. pseudoComplete：status=completed 但 stepDone<stepTotal 或 hasUnfinishedOutcome */
 export function parseManualProgressFromContent(content) {
     const fm = extractFrontmatter(content);
     const procedure = fm?.procedure ?? "(unknown)";
@@ -48,7 +64,33 @@ export function parseManualProgressFromContent(content) {
             nextStep = text;
         }
     }
-    return { procedure, stepDone, stepTotal, status, nextStep };
+    // 5. 抽 ## 执行状态 表的每行 outcome
+    const stepOutcomes = [];
+    // 表格行格式 `| N | <outcome> | <message> |`，message 列可空（`\s*` 兼容末列前的 0+ 空格）
+    const tableRe = /^\| (\d+) \| (.+?) \| [^\|]*\s*\|$/gm;
+    for (const m of content.matchAll(tableRe)) {
+        const idxStr = m[1] ?? "";
+        const rawOutcome = m[2] ?? "";
+        const idx = Number.parseInt(idxStr, 10);
+        if (Number.isFinite(idx) && idx > 0) {
+            stepOutcomes.push({
+                stepIndex: idx,
+                outcome: normalizeOutcome(rawOutcome),
+            });
+        }
+    }
+    const hasUnfinishedOutcome = stepOutcomes.some((o) => o.outcome === "—" || o.outcome === "INCONCLUSIVE");
+    const pseudoComplete = status === "completed" && (stepDone < stepTotal || hasUnfinishedOutcome);
+    return {
+        procedure,
+        stepDone,
+        stepTotal,
+        status,
+        nextStep,
+        stepOutcomes,
+        hasUnfinishedOutcome,
+        pseudoComplete,
+    };
 }
 function extractFrontmatter(content) {
     const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
@@ -69,15 +111,23 @@ function extractFrontmatter(content) {
     return out;
 }
 /** widget 渲染：3 行 string[]，给 `ui.setWidget("pt-manual", lines, { placement: "aboveEditor" })` 用。
- *  - 第 1 行：`pt ▶ <procedure>  step <done>/<total>  (<status>)`（completed 加 ` ✓ done`）
+ *  - 第 1 行：`pt ▶ <procedure>  step <done>/<total>  (<status>)`（completed 加 ` ✓ done`；pseudoComplete 加 `⚠ fake done`）
  *  - 第 2 行：`  next: <nextStep 文本>`（无 nextStep 时该行省略）
  *  - 第 3 行：`  file: <filePath>`
- *  status === completed 时仍显示，但 footer 后缀改 done；widget 撤掉由 caller 决定（见 index.ts refreshManualWidget）。 */
+ *  status === completed 时仍显示，但 footer 后缀改 done；widget 撤掉由 caller 决定（见 index.ts refreshManualWidget）。
+ *  v15.x（issue pt-manual-completion-check-too-loose）：pseudoComplete 时加 ⚠ 提示用户
+ *  （status=completed 但 stepDone<stepTotal 或 hasUnfinishedOutcome → 伪完成）。 */
 export function renderManualWidgetLines(filePath, p) {
-    const statusText = p.status === "completed" ? "✓ done" : `(${p.status})`;
+    let statusText;
+    if (p.status === "completed") {
+        statusText = p.pseudoComplete ? "⚠ fake done" : "✓ done";
+    }
+    else {
+        statusText = `(${p.status})`;
+    }
     const lines = [];
     lines.push(`pt ▶ ${p.procedure}  step ${p.stepDone}/${p.stepTotal}  ${statusText}`);
-    if (p.nextStep && p.status !== "completed") {
+    if (p.nextStep && !p.pseudoComplete && p.status !== "completed") {
         lines.push(`  next: ${p.nextStep}`);
     }
     lines.push(`  file: ${filePath}`);
@@ -85,16 +135,35 @@ export function renderManualWidgetLines(filePath, p) {
 }
 /** footer 后缀：有 activeManual 时追加。
  *  - in-progress → `· manual: <procedure> <done>/<total>`
- *  - completed   → `· manual: <procedure> done` */
+ *  - completed   → `· manual: <procedure> done`
+ *  - pseudoComplete（status=completed 但 stepDone<stepTotal 或 hasUnfinishedOutcome）→ `· manual: <procedure> ⚠ fake done` */
 export function renderManualFooterSuffix(p) {
     if (p.status === "completed") {
-        return `· manual: ${p.procedure} done`;
+        return p.pseudoComplete
+            ? `· manual: ${p.procedure} ⚠ fake done`
+            : `· manual: ${p.procedure} done`;
     }
     return `· manual: ${p.procedure} ${p.stepDone}/${p.stepTotal}`;
 }
-/** 文件存在 + status !== completed。配合 widget/footer 决定要不要展示。
+/** 检查 manual 实例是否应视为 active（widget 继续显示 + footer 显示）。
+ *  v15.x（issue pt-manual-completion-check-too-loose）：硬校验 status=completed 也需 step 全勾 + outcome 非 —/INCONCLUSIVE。
+ *  - status !== "completed" → true（active）
+ *  - status="completed" 但 stepDone < stepTotal → true（伪完成）
+ *  - status="completed" 但 hasUnfinishedOutcome → true（伪完成）
+ *  - status="completed" 且 stepDone === stepTotal 且无 —/INCONCLUSIVE → false（真完成） */
+export function checkManualCompletion(p) {
+    if (p.status !== "completed")
+        return true;
+    if (p.stepDone < p.stepTotal)
+        return true;
+    if (p.hasUnfinishedOutcome)
+        return true;
+    return false;
+}
+/** 文件存在 + checkManualCompletion(p) === true。配合 widget/footer 决定要不要展示。
  *  - 用 fs.access 探测存在（轻量，不读全文）
- *  - 真的 parse status 用 parseManualProgress（一次 readFile 取齐） */
+ *  - 真的 parse status 用 parseManualProgress（一次 readFile 取齐）
+ *  v15.x：status=completed 时不再直接判 active，需 checkManualCompletion 硬校验 */
 export async function isManualActive(filePath) {
     try {
         await access(filePath);
@@ -103,5 +172,7 @@ export async function isManualActive(filePath) {
         return false;
     }
     const p = await parseManualProgress(filePath);
-    return p !== null && p.status !== "completed";
+    if (!p)
+        return false;
+    return checkManualCompletion(p);
 }