@istuen/pt 0.1.1 → 0.1.2

package/src/manual-session.ts

@@ -28,6 +28,7 @@ import type {
   ExtensionUIContext,
 } from "@earendil-works/pi-coding-agent";
 import {
+  checkManualCompletion,
   isManualActive,
   parseManualProgress,
   renderManualFooterSuffix,
@@ -124,9 +125,12 @@ function refreshInjectionFooter(ui: ExtensionUIContext, session: SessionState):
 
 /** 刷新 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: ExtensionUIContext, session: SessionState): Promise<void> {
   const m = session.activeManual;
   if (!m) {
@@ -135,7 +139,7 @@ async function refreshManualWidget(ui: ExtensionUIContext, session: SessionState
     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/src/manual-track.ts

@@ -13,17 +13,37 @@
 
 import { access, readFile } from "node:fs/promises";
 
+/** ## 执行状态 表的 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（容错，不抛）。 */
@@ -37,12 +57,25 @@ export async function parseManualProgress(filePath: string): Promise<ManualProgr
   }
 }
 
+/** 规范化 Outcome 列字符串到 OutcomeKind。未识别值归 INCONCLUSIVE（保守按未完成处理）。 */
+function normalizeOutcome(raw: string): OutcomeKind {
+  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: string): ManualProgress | null {
   const fm = extractFrontmatter(content);
   const procedure = fm?.procedure ?? "(unknown)";
@@ -64,7 +97,37 @@ export function parseManualProgressFromContent(content: string): ManualProgress
     }
   }
 
-  return { procedure, stepDone, stepTotal, status, nextStep };
+  // 5. 抽 ## 执行状态 表的每行 outcome
+  const stepOutcomes: StepOutcome[] = [];
+  // 表格行格式 `| 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,
+  };
 }
 
 /** frontmatter 抽取（极简 YAML：只解 key: value）。 */
@@ -88,15 +151,22 @@ function extractFrontmatter(content: string): SimpleFrontmatter | 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 function renderManualWidgetLines(filePath: string, p: ManualProgress): string[] {
-  const statusText = p.status === "completed" ? "✓ done" : `(${p.status})`;
+  let statusText: string;
+  if (p.status === "completed") {
+    statusText = p.pseudoComplete ? "⚠ fake done" : "✓ done";
+  } else {
+    statusText = `(${p.status})`;
+  }
   const lines: string[] = [];
   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}`);
@@ -105,17 +175,34 @@ export function renderManualWidgetLines(filePath: string, p: ManualProgress): st
 
 /** 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: ManualProgress): string {
   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: ManualProgress): boolean {
+  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: string): Promise<boolean> {
   try {
     await access(filePath);
@@ -123,5 +210,6 @@ export async function isManualActive(filePath: string): Promise<boolean> {
     return false;
   }
   const p = await parseManualProgress(filePath);
-  return p !== null && p.status !== "completed";
+  if (!p) return false;
+  return checkManualCompletion(p);
 }

package/src/manual-writeback.ts

@@ -0,0 +1,227 @@
+// 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/ 层
+
+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 内容里扫 step + observe，建立 stepIndex → StepMatch 索引。
+ *  算法：
+ *   1. 逐行扫描：step 行 `^- \[([ x])\] (.+)$` 记录 stepIndex（1-indexed 累计）——兼容已勾选 `- [x]`；
+ *      验证参照行 `^  - 验证参照：(.+)$` 关联到上一个 step。
+ *   2. step 行格式兼容：`^- \[ \] \d+\. xxx`（旧版 buildManualDoc）也支持（取 \d+ 后内容）。
+ *  失败返回空 Map（不含任何 step）。 */
+function indexSteps(content: string): Map<number, StepMatch> {
+  const out = new Map<number, StepMatch>();
+  let stepIndex = 0;
+  let lastStep: StepMatch | null = 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: string, probeName: string): StepMatch | null {
+  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: string): Set<string> {
+  const out = new Set<string>();
+  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: Set<string>): string {
+  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: string,
+  probeName: string,
+  outcome: ProbeOutcomeKind,
+  message: string
+): WritebackResult {
+  const baseResult: WritebackResult = {
+    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: number[] = [];
+  const checklistLines: string[] = []; // [{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/src/parse/index.ts

@@ -37,6 +37,17 @@ 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: ReadonlyMap<string, string> = new Map([
+  ["prj", "project"],
+  ["gbl", "global"],
+  ["pt", "builtin"],
+]);
 export const mdAdapter: SourceAdapter = {
   name: "md",
 
@@ -182,8 +193,16 @@ function findActiveProfile(
   profileRef: string
 ): Profile {
   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/dist/builtin/assets/domains/pack-repair.md

@@ -1,47 +0,0 @@
----
-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/src/builtin/assets/domains/pack-repair.md

@@ -1,47 +0,0 @@
----
-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 / 后台进程