@istuen/pt 0.1.0 → 0.1.2

package/dist/manual-writeback.d.ts

@@ -0,0 +1,37 @@
+import type { ProbeOutcomeKind } from "./schema.js";
+/** findStepForProbe 返回结构（probe 命中的 step 信息） */
+export interface StepMatch {
+    /** step 的 1-indexed 编号（对应 manual 文件 ## 执行状态 表的行号） */
+    stepIndex: number;
+    /** step 的 desc 文本（去 "- [ ] " 前缀） */
+    desc: string;
+    /** step 的 observe 列表（来自 `  - 验证参照：xxx, yyy` 行） */
+    observeNames: string[];
+}
+/** writeProbeResult 返回结构 */
+export interface WritebackResult {
+    /** 匹配上的 step 数（0 = probe 名不在任何 step 的 observe 中） */
+    matchCount: number;
+    /** 写回的 step 索引（1-indexed） */
+    stepIndexes: number[];
+    /** 因全部 observe 完成而勾选 checklist 的 step 索引（1-indexed） */
+    checkedSteps: number[];
+    /** 改后的文件内容（changed=false 时返回原 content） */
+    content: string;
+    /** 是否真的改了文件 */
+    changed: boolean;
+    /** 改后的 completed-probes 列表（含历史 + 本次） */
+    completedProbes: string[];
+}
+/** 从 manual 内容里按 probe 名找匹配的 step。多个 step 有同一 observe 时取首个。
+ *  返回 null = probe 名不在任何 step 的 observe 中。 */
+export declare function findStepForProbe(content: string, probeName: string): StepMatch | null;
+/** 写回 probe 结果到 manual 文件内容（同步，不读文件）。
+ *  - 写执行状态表 `| N | — | |` → `| N | <outcome> | <message> |`
+ *  - 改 frontmatter 注释维护 completed probe 列表
+ *  - 多 observe 同步：若 step 的全部 observe 都 in 列表 → checklist `- [ ]` → `- [x]`
+ *  - 幂等：同一 probe 跑两次 → 用最新覆盖原 message
+ *  - 边界：
+ *    - 找不到匹配 step → matchCount=0, changed=false（让 caller 走 warn 分支）
+ *    - 找不到执行状态表对应行 → 不改（保守：manual 损坏不擅自补） */
+export declare function writeProbeResult(content: string, probeName: string, outcome: ProbeOutcomeKind, message: string): WritebackResult;

package/dist/manual-writeback.js

@@ -0,0 +1,195 @@
+// src/manual-writeback.ts — pt_verify 结果自动写回 manual 实例（纯函数内核）
+//
+// v15.x（issue pt-verify-result-not-written-back-to-manual）：
+// pt_verify tool 跑完 probe 后，自动把结果写回 activeManual 文件的 ## 执行状态 表。
+// 闭环不靠 LLM 自觉——与 pt-collab.md 的 acceptance 原则一致。
+//
+// 设计要点：
+// - probe ↔ step 映射：按 FlowStep.observe 列表匹配 probe 名（首个匹配）
+// - 多 observe 同步：frontmatter 注释维护已完成 probe 列表；该 step 全部 observe 都
+//   完成时 checklist `- [ ]` → `- [x]`
+// - 写回幂等：同一 probe 跑两次 → 用最新 outcome/message 覆盖原行
+// - 纯函数：writeProbeResult 只改字符串，不碰 IO；IO 由 caller 包 withFileMutationQueue
+//
+// 边界纪律：
+// - 不动 parseManualProgress / renderManualWidgetLines / renderManualFooterSuffix
+//   （manual-track.ts 保持纯解析语义，写回是上层职责）
+// - 不依赖 ExtensionAPI，可单测
+// - manual 实例文件不是 Pt 资产（不是 Domain/Blueprint/Profile）→ 不进 parse/ 层
+/** 从 manual 内容里扫 step + observe，建立 stepIndex → StepMatch 索引。
+ *  算法：
+ *   1. 逐行扫描：step 行 `^- \[([ x])\] (.+)$` 记录 stepIndex（1-indexed 累计）——兼容已勾选 `- [x]`；
+ *      验证参照行 `^  - 验证参照：(.+)$` 关联到上一个 step。
+ *   2. step 行格式兼容：`^- \[ \] \d+\. xxx`（旧版 buildManualDoc）也支持（取 \d+ 后内容）。
+ *  失败返回空 Map（不含任何 step）。 */
+function indexSteps(content) {
+    const out = new Map();
+    let stepIndex = 0;
+    let lastStep = null;
+    const lines = content.split("\n");
+    for (const line of lines) {
+        // step 行：兼容 "- [ ] desc" / "- [x] desc" / "- [ ] N. desc" / "- [x] N. desc"
+        // 多轮 writeback 场景下，已勾选 step 必须算入索引（避免后续 step 索引错乱）
+        const stepMatch = line.match(/^- \[[ x]\]\s+(?:\d+\.\s+)?(.+)$/);
+        if (stepMatch) {
+            stepIndex++;
+            lastStep = {
+                stepIndex,
+                desc: (stepMatch[1] ?? "").trim(),
+                observeNames: [],
+            };
+            out.set(stepIndex, lastStep);
+            continue;
+        }
+        // observe 行（紧跟 step 的子项）
+        const observeMatch = line.match(/^ {2}- 验证参照：(.+)$/);
+        if (observeMatch && lastStep) {
+            const names = (observeMatch[1] ?? "")
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            lastStep.observeNames = names;
+        }
+    }
+    return out;
+}
+/** 从 manual 内容里按 probe 名找匹配的 step。多个 step 有同一 observe 时取首个。
+ *  返回 null = probe 名不在任何 step 的 observe 中。 */
+export function findStepForProbe(content, probeName) {
+    if (!probeName)
+        return null;
+    const steps = indexSteps(content);
+    for (const step of steps.values()) {
+        if (step.observeNames.includes(probeName)) {
+            return step;
+        }
+    }
+    return null;
+}
+/** 解析 frontmatter 注释里的 completed probes 列表（pt-verify-completed 行）。
+ *  格式：<!-- pt-verify-completed: probe1, probe2, probe3 -->
+ *  缺省返空 Set。 */
+function parseCompletedProbes(content) {
+    const out = new Set();
+    const m = content.match(/<!--\s*pt-verify-completed:\s*([\s\S]*?)\s*-->/);
+    if (!m?.[1])
+        return out;
+    for (const name of m[1].split(",")) {
+        const trimmed = name.trim();
+        if (trimmed.length > 0)
+            out.add(trimmed);
+    }
+    return out;
+}
+/** 把 completed probes Set 序列化成 frontmatter 注释行（含前后空格）。
+ *  若 Set 为空，返回空字符串（删除注释行时不主动清，由 caller 决定）。 */
+function renderCompletedProbes(probes) {
+    if (probes.size === 0)
+        return "";
+    const list = [...probes].sort().join(", ");
+    return `<!-- pt-verify-completed: ${list} -->`;
+}
+/** 写回 probe 结果到 manual 文件内容（同步，不读文件）。
+ *  - 写执行状态表 `| N | — | |` → `| N | <outcome> | <message> |`
+ *  - 改 frontmatter 注释维护 completed probe 列表
+ *  - 多 observe 同步：若 step 的全部 observe 都 in 列表 → checklist `- [ ]` → `- [x]`
+ *  - 幂等：同一 probe 跑两次 → 用最新覆盖原 message
+ *  - 边界：
+ *    - 找不到匹配 step → matchCount=0, changed=false（让 caller 走 warn 分支）
+ *    - 找不到执行状态表对应行 → 不改（保守：manual 损坏不擅自补） */
+export function writeProbeResult(content, probeName, outcome, message) {
+    const baseResult = {
+        matchCount: 0,
+        stepIndexes: [],
+        checkedSteps: [],
+        content,
+        changed: false,
+        completedProbes: [],
+    };
+    if (!probeName)
+        return baseResult;
+    const steps = indexSteps(content);
+    if (steps.size === 0)
+        return baseResult;
+    const match = findStepForProbe(content, probeName);
+    if (!match)
+        return baseResult;
+    baseResult.matchCount = 1;
+    baseResult.stepIndexes.push(match.stepIndex);
+    // 1. 改执行状态表对应行（幂等覆盖：找 `| N | ... |` 任意中间值）
+    // `.+` 贪婪匹配到最后一个 ` |$`，覆盖已填行（COMPLETED|DEVIATED|INCONCLUSIVE）。
+    let out = content;
+    const statusLineRe = new RegExp(`^\\| ${match.stepIndex} \\| .+ \\|$`, "m");
+    if (statusLineRe.test(out)) {
+        // 转义 message 里的 | 字符（避免破坏 markdown 表格）+ 反斜杠（避免后续正则误判）
+        const safeMsg = message.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+        out = out.replace(statusLineRe, `| ${match.stepIndex} | ${outcome} | ${safeMsg} |`);
+    }
+    // 2. 维护 frontmatter 注释里的 completed probes 列表
+    const completed = parseCompletedProbes(out);
+    completed.add(probeName);
+    baseResult.completedProbes = [...completed];
+    // 写回或追加 frontmatter 注释
+    const commentRe = /<!--\s*pt-verify-completed:\s*[\s\S]*?-->/;
+    const newComment = renderCompletedProbes(completed);
+    if (commentRe.test(out)) {
+        out = out.replace(commentRe, newComment);
+    }
+    else if (newComment) {
+        // 追加到 frontmatter 后空行（frontmatter 后第一个空行）
+        const fmEndRe = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/m;
+        const fmMatch = out.match(fmEndRe);
+        if (fmMatch?.index !== undefined) {
+            const insertAt = fmMatch.index + fmMatch[0].length;
+            out = out.slice(0, insertAt) + `\n${newComment}\n` + out.slice(insertAt);
+        }
+        else {
+            // 无 frontmatter（不应该，但兼容）→ 追加到文件头
+            out = `${newComment}\n${out}`;
+        }
+    }
+    // 3. 多 observe 同步：若 step 的全部 observe 都 in completed → checklist 打勾
+    const checkedSteps = [];
+    const checklistLines = []; // [{lineIdx, newLine}] 延迟到循环外统一 replace
+    const lines = out.split("\n");
+    // 复用 indexSteps 但要在已更新的 out 里重新解析（completed 变了不影响 step 索引）
+    const freshSteps = indexSteps(out);
+    for (const [idx, step] of freshSteps) {
+        if (step.observeNames.length === 0)
+            continue;
+        const allCompleted = step.observeNames.every((n) => completed.has(n));
+        if (!allCompleted)
+            continue;
+        // 找该 step 对应的 checklist 行（兼容已勾选 - [x]）
+        let stepLineIdx = -1;
+        let lineNum = 0;
+        let sIdx = 0;
+        for (const line of lines) {
+            if (line.match(/^- \[[ x]\]\s+(?:\d+\.\s+)?.+$/)) {
+                sIdx++;
+                if (sIdx === idx) {
+                    stepLineIdx = lineNum;
+                    break;
+                }
+            }
+            lineNum++;
+        }
+        if (stepLineIdx === -1)
+            continue;
+        const oldLine = lines[stepLineIdx];
+        if (oldLine === undefined)
+            continue;
+        const newLine = oldLine.replace(/^- \[ \]/, "- [x]");
+        if (newLine !== oldLine) {
+            lines[stepLineIdx] = newLine;
+            checkedSteps.push(idx);
+        }
+    }
+    if (checkedSteps.length > 0) {
+        out = lines.join("\n");
+        baseResult.checkedSteps = checkedSteps;
+    }
+    baseResult.content = out;
+    baseResult.changed = out !== content;
+    return baseResult;
+}

package/dist/parse/index.d.ts

@@ -2,8 +2,5 @@ import type { SourceAdapter } from "../schema.js";
 import { parseBlueprint } from "./blueprint.js";
 import { parseDomain } from "./domain.js";
 import { parseProfile } from "./profile.js";
-/** MD adapter：按目录位置分发到 domain/blueprint/profile adapter，组装 SchemaBundle。
- *  v9 命名约定：适配的是 MD 文件格式（不再叫 OXN——OXN 是历史名）。
- *  v15.x PR1（§3.1）：内部构造 4 类 AssetPack → loadXxx → N 元 dedupByNameN。 */
 export declare const mdAdapter: SourceAdapter;
 export { parseBlueprint, parseDomain, parseProfile };

package/dist/parse/index.js

@@ -20,6 +20,16 @@ import { parseProfile } from "./profile.js";
 /** MD adapter：按目录位置分发到 domain/blueprint/profile adapter，组装 SchemaBundle。
  *  v9 命名约定：适配的是 MD 文件格式（不再叫 OXN——OXN 是历史名）。
  *  v15.x PR1（§3.1）：内部构造 4 类 AssetPack → loadXxx → N 元 dedupByNameN。 */
+/** v15.x §2.4.4：位置 alias 短名 → source（位置指针独立于 pack.name）。
+ *  用于 findActiveProfile 查位置 alias（kind="location"）时按 source 查 pack，
+ *  与 pack.name 解耦——builtin pack 加 manifest.name="pt-builtin" 后 @pt/... 仍能寻址。
+ *  key 是 parseRef 输出的位置 alias 短名（prj/gbl/pt），value 是 AssetPack.source。
+ *  与 LOC_ALIAS（source → alias）是反向表，互不重复定义。 */
+const ALIAS_TO_SOURCE = new Map([
+    ["prj", "project"],
+    ["gbl", "global"],
+    ["pt", "builtin"],
+]);
 export const mdAdapter = {
     name: "md",
     async load(cwd, profileName, adapterCtx) {
@@ -148,8 +158,15 @@ export const mdAdapter = {
  *  v15.x PR4：settings 倒序逻辑由 mdAdapter.load 构造 packs 时已处理，findActiveProfile 不变。 */
 function findActiveProfile(packs, packProfiles, profileRef) {
     if (profileRef.startsWith("@")) {
-        const { pack, name } = parseRef(profileRef, ""); // 限定 ref 不需要 selfPack
-        const packIdx = packs.findIndex((p) => p.name === pack);
+        const { kind, pack, name } = parseRef(profileRef, ""); // 限定 ref 不需要 selfPack
+        // v15.x §2.4.4：位置 alias（@prj/@gbl/@pt，kind="location"）按 source 查（固定 3 slot 物理位置指针），
+        // 与 pack.name 解耦——builtin pack 加 manifest.name 后，pack.name 变化不影响 @pt/... 寻址。
+        // 身份 alias（kind="identity"）按 pack.name 查（manifest.name 身份指针）。
+        const packIdx = kind === "location"
+            ? ALIAS_TO_SOURCE.has(pack)
+                ? packs.findIndex((p) => p.source === ALIAS_TO_SOURCE.get(pack))
+                : -1
+            : packs.findIndex((p) => p.name === pack);
         if (packIdx < 0) {
             throw new Error(`active profile "@${pack}/${name}" references unknown pack "${pack}"`);
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@istuen/pt",
-  "version": "0.1.0",
-  "description": "Pt \u2014 Turn domain knowledge into configurable Agent Context.",
+  "version": "0.1.2",
+  "description": "Pt — Turn domain knowledge into configurable Agent Context.",
   "type": "module",
   "keywords": [
     "pi-package"

package/src/asset-pack/manifest.ts

@@ -14,6 +14,7 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { errMsg } from "../diagnostics.js";
+import type { PackSource } from "../schema.js";
 
 /** manifest 解析结果。ok=false 表示文件不存在/解析失败/校验不过——调用方走默认值。 */
 export interface ParsedManifest {
@@ -55,9 +56,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: string): Promise<ParsedManifest> {
+export async function parseManifest(rootDir: string, source?: PackSource): Promise<ParsedManifest> {
   const file = join(rootDir, "pt-asset-pack.yaml");
   let raw: string;
   try {
@@ -87,9 +92,16 @@ export async function parseManifest(rootDir: string): Promise<ParsedManifest> {
   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`);
-    } else if (RESERVED_NAMES.has(n)) {
-      warnings.push(`manifest.name "${n}" is reserved, 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) && 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;
     }
@@ -99,7 +111,9 @@ export async function parseManifest(rootDir: string): Promise<ParsedManifest> {
   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/src/asset-pack/md-file-pack.ts

@@ -89,15 +89,31 @@ export class MdFilePack implements AssetPack {
     source: PackSource;
     adapterCtx?: SourceAdapterContext;
   }): Promise<MdFilePack> {
-    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）：

package/src/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/src/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/src/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/src/index.ts

@@ -23,7 +23,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 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";
@@ -73,6 +73,7 @@ import {
   refreshManualWidget,
   tryRestoreManual,
 } from "./manual-session.js";
+import { writeProbeResult } from "./manual-writeback.js";
 import { slog } from "./slog.js";
 
 type AgentUIContext = NonNullable<AgentAPI["ui"]>;
@@ -943,15 +944,39 @@ export default function (pi: ExtensionAPI): void {
             : `? ${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 },
       };
     },
   });