@genee/omp-opsx-addon 0.7.0 → 0.9.0

package/lib/usage-poller.ts

@@ -108,6 +108,15 @@ export const DEFAULT_RENDER_TICK_MS = 1_000;
 export const DEFAULT_MIN_FETCH_INTERVAL_MS = 10_000;
 /** Default idle fallback period (60s): providers with no consumption still re-fetch. */
 export const DEFAULT_IDLE_DIRTY_MS = 60_000;
+/**
+ * Default wall-time budget for the cold-start refresh inside
+ * {@link startSharedPoller}. `session_start` awaits this function; if the
+ * initial network fetch hasn't settled within the budget it detaches to the
+ * background instead of pinning the extension handler (the host aborts event
+ * handlers at 30s). Disk-seeded data renders immediately and the 1s tick picks
+ * the fetch result up as soon as it lands.
+ */
+export const DEFAULT_STARTUP_FETCH_BUDGET_MS = 3_000;
 /** Threshold for a "即将重置" forced fetch: any window resetting within this. */
 export const RESET_IMMINENT_MS = 60_000;
 
@@ -121,6 +130,8 @@ export interface StartPollerOptions {
     minFetchIntervalMs?: number;
     /** Idle fallback: providers whose last successful fetch is older than this get marked dirty. Default 60s. */
     idleDirtyMs?: number;
+    /** Max wall time the cold-start network refresh may block the caller before detaching to background. Default 3s. */
+    startupFetchBudgetMs?: number;
     /** Fired once at the end of every tick (after syncFromDisk + any fetch). */
     onTick?: () => void;
     /** Whether the calling session owns a real UI surface. A non-UI session (in-process task subagent whose ctx.ui is a no-op) must NOT steal the tick-render callback from the UI-owning session. */
@@ -1003,6 +1014,35 @@ async function fetchProvider(
     }
 }
 
+/**
+ * Run the cold-start fetch but release the caller after `budgetMs` at most.
+ *
+ * `session_start` awaits the poller startup; a blackholed network otherwise
+ * pins the extension handler until the host's 30s gate. The in-flight fetch
+ * keeps running detached (direct fetchers carry their own hard timeout, and
+ * fetchProvider swallows per-provider errors), so the result still lands via
+ * the 1s render tick. `budgetMs <= 0` detaches immediately.
+ */
+async function fetchDueWithStartupBudget(startFetch: () => Promise<void>, budgetMs: number): Promise<void> {
+    const initial = startFetch();
+    if (budgetMs <= 0) {
+        void initial.then(() => {}, () => {});
+        return;
+    }
+    let settled = false;
+    initial.then(() => { settled = true; }, () => { settled = true; });
+    let budgetTimer: NodeJS.Timeout | undefined;
+    const budget = new Promise<void>((resolve) => {
+        budgetTimer = setTimeout(resolve, budgetMs);
+    });
+    try {
+        await Promise.race([initial, budget]);
+    } finally {
+        clearTimeout(budgetTimer);
+    }
+    if (!settled) return; // budget elapsed: keep the fetch running detached
+}
+
 /**
  * Fetch every dirty provider whose per-provider minimum-interval floor has
  * elapsed (skipping in-flight ones), consuming the dirty marks on initiation.
@@ -1225,7 +1265,10 @@ export async function startSharedPoller(
         if (fresh) return;
 
         evaluateDirty(computeLoggedIn());
-        await fetchDue(authStorage, directFetchers, getApiKey);
+        await fetchDueWithStartupBudget(
+            () => fetchDue(authStorage, directFetchers, getApiKey),
+            opts?.startupFetchBudgetMs ?? DEFAULT_STARTUP_FETCH_BUDGET_MS,
+        );
     })();
     try {
         await startInFlight;

package/lib/usage-render.ts

@@ -48,6 +48,12 @@ export interface Painter {
     header(label: string, brandAnsi: string): string;
     /** Numeric balance text (e.g. "余额 ¥18.06"), text-colored. */
     balance(text: string): string;
+    /**
+     * Muted/secondary spans — dim-colored so they never compete with the
+     * content for visual weight: the inline concurrency token, and the bar's
+     * closing rule.
+     */
+    muted(text: string): string;
     /**
      * Waveform layer paint — btop row gradient over the provider's brand hue.
      * `brandAnsi` is the raw brand SGR ('' → accent fallback, like header).
@@ -98,6 +104,7 @@ export const ansiPainter: Painter = {
     sep: ` ${D}│${R} `,
     header: (label, brandAnsi) => c(brandAnsi ? BOLD + brandAnsi : BOLD, label),
     balance: (text) => c(WHITE, text),
+    muted: (text) => c(D, text),
     wave: (brandAnsi, layer, text) => c(layer === 'bottom' ? bottomShade(brandAnsi || CYAN) : brandAnsi || CYAN, text),
 };
 
@@ -109,6 +116,7 @@ export function themePainter(theme: PainterTheme): Painter {
         sep: ` ${theme.fg('dim', '│')} `,
         header: (label, brandAnsi) => (brandAnsi ? c(brandAnsi, label) : theme.fg('accent', label)),
         balance: (text) => theme.fg('text', text),
+        muted: (text) => theme.fg('dim', text),
         wave: (brandAnsi, layer, text) =>
             brandAnsi
                 ? c(layer === 'bottom' ? bottomShade(brandAnsi) : brandAnsi, text)
@@ -123,7 +131,7 @@ export function themePainter(theme: PainterTheme): Painter {
 // Unknown providers fall back to the omp registry display name, then the raw id.
 const PROVIDER: Record<string, { label: string; color: string }> = {
     'zhipu-coding-plan': { label: '智谱', color: PURPLE },
-    zai: { label: '智谱', color: PURPLE },
+    zai: { label: 'Z.AI', color: PURPLE },
     'kimi-code': { label: 'Kimi', color: CYAN },
     'minimax-code-cn': { label: 'MiniMax', color: X },
     'ark-coding-plan': { label: '火山方舟', color: CYAN },
@@ -385,8 +393,28 @@ const padRight = (s: string, width: number): string => {
     return v >= width ? s : s + ' '.repeat(width - v);
 };
 
+/**
+ * Per-provider adaptive-concurrency view the inline header token renders:
+ * the controller's current limit `L` and the allowed `ceiling`. The assembly
+ * layer builds this from `ConcurrencyController.stateFor(provider)`; a provider
+ * absent from the map renders exactly as it did before this token existed.
+ */
+export interface ConcurrencyInlineView {
+    /** Current adaptive limit (L). */
+    limit: number;
+    /** Upper bound of the allowed range. */
+    ceiling: number;
+    /** Lease held read-only (no writes this process) → append the `⚠` mark. */
+    degraded?: boolean;
+}
+
 export function renderUsageReports(
     reports: UsageReport[],
+    /**
+     * Render width in cells. Provider rows IGNORE it (they keep their natural
+     * width — roomy over compact), but the closing rule is bounded by it, so it
+     * tracks the terminal instead of wrapping.
+     */
     maxWidth = 120,
     painter: Painter = ansiPainter,
     placeholderIds?: readonly string[],
@@ -394,6 +422,12 @@ export function renderUsageReports(
     consumptionTracks?: Map<string, ConsumptionTrack>,
     usageEstimates?: Map<string, string>,
     exhaustedProviders?: ReadonlySet<string>,
+    /**
+     * Inline adaptive-concurrency token per managed provider, appended to that
+     * provider's header row (dim, after the name) — never a trailing block.
+     * Omitted/empty keeps the pre-existing output byte-for-byte identical.
+     */
+    concurrencyViews?: ReadonlyMap<string, ConcurrencyInlineView>,
 ): string[] {
     // Placeholder providers are logged-in but unfetched this round. Their ids are
     // explicit (never inferred from `limits.length === 0`); dedupe against reports
@@ -403,6 +437,17 @@ export function renderUsageReports(
     if (!reports?.length && placeholders.length === 0) return [];
     const loading = loadingProviders ?? new Set<string>();
 
+    // Inline concurrency token: header row only, and only for managed providers.
+    // Runs BEFORE the per-block width pass, so the injected token participates
+    // in the block's natural width and multi-block separators stay aligned.
+    const withConcurrency = (provider: string, col: string[]): string[] => {
+        const view = concurrencyViews?.get(provider);
+        if (!view || col.length === 0) return col;
+        // Token shape: `L/ceiling`, plus `⚠` on a read-only-lease degradation.
+        const token = `${view.limit}/${view.ceiling}${view.degraded ? '⚠' : ''}`;
+        return [`${col[0]} ${painter.muted(token)}`, ...col.slice(1)];
+    };
+
     // Build each provider column (header + usage / placeholder). Each block
     // aligns its OWN lines to its own natural width (header/body/waveform
     // share that block's width so the separators stack vertically) — blocks
@@ -422,12 +467,12 @@ export function renderUsageReports(
         // Second-level estimate override replaces the usage line (balance style).
         const est = usageEstimates?.get(r.provider);
         if (est && col.length >= 2) col[1] = painter.balance(est);
-        return { provider: r.provider, col, width: 0 };
+        return { provider: r.provider, col: withConcurrency(r.provider, col), width: 0 };
     });
     for (const id of placeholders) {
         cols.push({
             provider: id,
-            col: buildPlaceholderColumn(id, painter, loading.has(id), exhaustedProviders?.has(id)),
+            col: withConcurrency(id, buildPlaceholderColumn(id, painter, loading.has(id), exhaustedProviders?.has(id))),
             width: 0,
         });
     }
@@ -459,7 +504,8 @@ export function renderUsageReports(
     // beyond `maxWidth` rather than squeezing content or breaking to a second
     // line (user preference: roomy over compact). Blocks shorter than the
     // tallest contribute a cell padded to that block's own width on missing
-    // rows, so every separator keeps its column.
+    // rows, so every separator keeps its column. Only the rule appended below
+    // is bounded by `maxWidth`.
     const multi = valid.length > 1;
     const n = Math.max(...valid.map((c) => c.col.length));
     const out: string[] = [];
@@ -470,6 +516,13 @@ export function renderUsageReports(
         });
         out.push(cells.join(painter.sep));
     }
+    // Closing rule under the whole bar — the layout's ONLY width-bounded row
+    // (content rows keep their natural width above). `maxWidth` is the caller's
+    // live render width: the terminal width on the component path (re-read on
+    // every resize), columns minus slack on the print path. Bounding it here is
+    // what keeps it from wrapping — an over-wide row soft-wraps the terminal,
+    // and this bar never wraps.
+    out.push(painter.muted('─'.repeat(Math.max(1, Math.trunc(maxWidth)))));
     return out;
 }
 // ── token consumption waveform (Braille, design Decision 5) ─────────

package/lib/usage-widget.ts

@@ -1,7 +1,7 @@
 import { truncateToWidth, type Component } from "@oh-my-pi/pi-tui";
 import type { ExtensionUiComponentFactory } from "@oh-my-pi/pi-coding-agent";
 import type { UsageReport } from "@oh-my-pi/pi-ai";
-import { buildColumn, renderUsageReports, themePainter, type Painter, type ConsumptionTrack } from "./usage-render.js";
+import { buildColumn, renderUsageReports, themePainter, type Painter, type ConsumptionTrack, type ConcurrencyInlineView } from "./usage-render.js";
 
 /**
  * A single provider rendered as a standalone, reusable pi-tui `Component`.
@@ -58,6 +58,7 @@ export class UsageTable implements Component {
     readonly #consumptionTracks?: Map<string, ConsumptionTrack>;
     readonly #usageEstimates?: Map<string, string>;
     readonly #exhaustedProviders?: ReadonlySet<string>;
+    readonly #concurrencyViews?: ReadonlyMap<string, ConcurrencyInlineView>;
 
     constructor(
         reports: UsageReport[],
@@ -67,6 +68,12 @@ export class UsageTable implements Component {
         consumptionTracks?: Map<string, ConsumptionTrack>,
         usageEstimates?: Map<string, string>,
         exhaustedProviders?: ReadonlySet<string>,
+        /**
+         * Inline per-provider concurrency tokens (see `renderUsageReports`),
+         * appended to each managed provider's header row. Omitted/empty →
+         * byte-identical legacy output.
+         */
+        concurrencyViews?: ReadonlyMap<string, ConcurrencyInlineView>,
     ) {
         this.#reports = reports;
         this.#painter = painter;
@@ -75,11 +82,14 @@ export class UsageTable implements Component {
         this.#consumptionTracks = consumptionTracks;
         this.#usageEstimates = usageEstimates;
         this.#exhaustedProviders = exhaustedProviders;
+        this.#concurrencyViews = concurrencyViews;
     }
 
     render(width: number): readonly string[] {
         // Per-provider consumption tracks are threaded into the layout kernel,
-        // which embeds each chart inside its own provider column.
+        // which embeds each chart inside its own provider column. The live
+        // `width` also sizes the kernel's closing rule, so a resize re-render
+        // re-fits the rule to the terminal.
         return renderUsageReports(
             this.#reports,
             Math.max(1, Math.trunc(width)),
@@ -89,6 +99,7 @@ export class UsageTable implements Component {
             this.#consumptionTracks,
             this.#usageEstimates,
             this.#exhaustedProviders,
+            this.#concurrencyViews,
         );
     }
 
@@ -103,7 +114,8 @@ export class UsageTable implements Component {
  * current reports (mirroring the dashboard precedent), which re-injects the then-
  * current theme. Returns a `Container`-free `UsageTable` directly: rows extend
  * at their natural width (the kernel never wraps — a row can run past `width`),
- * and `ProviderCard.render`'s `truncateToWidth` is the only truncation seam.
+ * the kernel's closing rule is the one row that does track `width`, and
+ * `ProviderCard.render`'s `truncateToWidth` is the only truncation seam.
  * Wrapping each row in `pi-tui`'s `Text` would both drop the single-row
  * natural-width blank separators (Text renders empty input as `[]`) and repad
  * every line to the full width — losing byte parity with the RPC/print path
@@ -116,6 +128,8 @@ export function createUsageWidget(
     consumptionTracks?: Map<string, ConsumptionTrack>,
     usageEstimates?: Map<string, string>,
     exhaustedProviders?: ReadonlySet<string>,
+    /** Inline per-provider concurrency tokens appended to header rows (optional). */
+    concurrencyViews?: ReadonlyMap<string, ConcurrencyInlineView>,
 ): ExtensionUiComponentFactory {
-    return (_tui, theme) => new UsageTable(reports, themePainter(theme), placeholderIds, loadingProviders, consumptionTracks, usageEstimates, exhaustedProviders);
+    return (_tui, theme) => new UsageTable(reports, themePainter(theme), placeholderIds, loadingProviders, consumptionTracks, usageEstimates, exhaustedProviders, concurrencyViews);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genee/omp-opsx-addon",
-  	  "version": "0.7.0",
+  	  "version": "0.9.0",
   "type": "module",
   "description": "Pi Extension: OpenSpec workflow orchestration - coder/reviewer/planner agents, session title & progress",
   "main": "./index.ts",

package/skills/opsx-orchestration-protocol/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: opsx-orchestration-protocol
+description: opsx 四角色（coder / code-reviewer / planner / proposal-reviewer）共享的自定义编排协议——scratchpad 四区共享缓存与角色读写矩阵、supersede 权威语义与两档客观判据、无关状态硬栅栏（仅 coder）、P0/P1 评审闭环与轮次上限、报告契约、生效与兜底。
+---
+
+# OpenSpec 四角色编排协议
+
+本技能是 `@genee/omp-opsx-addon` 的 coder / code-reviewer / planner / proposal-reviewer 四个 agent 共享编排协议的**单一真源**。四份 agent 模板不复述本协议，只保留指向本技能的指针；协议口径的维护只改本文件。
+
+## scratchpad 四区共享缓存与角色读写矩阵
+
+变更目录下维护 `openspec/changes/<name>/scratchpad.md` 作为四角色共享探索缓存（与 proposal.md / design.md / tasks.md 同级），固定四阶段分区：
+
+- `## 调研与设计`：调研结论、涉及文件（`path:line`）、已排除方案
+- `## 提案审查关注点`：proposal-reviewer 审查报告中的 P0/P1 与关注点（经主 agent 中转回流）
+- `## 实现探索`：coder 每轮 append 的关键符号/数据流、新增涉及文件、验证/构建命令、已排除假设
+- `## 代码审查范围`：code-reviewer 审查报告中的 P0/P1 与验证范围结论（经主 agent 中转回流）
+
+条目一律标注轮次与角色，形如 `- [R<n> planner] <结论>`、`- [R<n> coder] <结论>`、`- [R<n> proposal-reviewer] <结论>`、`- [R<n> code-reviewer] <结论>`；涉及文件记 `path:line`。
+
+读写矩阵：
+
+| 角色 | scratchpad.md 权限 |
+| --- | --- |
+| planner | 创建 + 写入：出提案时 MUST 创建并写入四阶段骨架，预填「调研与设计」初始骨架（调研结论、涉及文件、已排除方案） |
+| coder | 读取 + 写入：开工前 MUST 先读；交付前把本轮新探索结论 append 进「实现探索」区；收到主 agent 中转的 code-reviewer P0/P1 时，开工前先把关注点 append 进「代码审查范围」区再修复 |
+| proposal-reviewer | 只读，不改写：审查前 MUST 先读（若存在），复用其中调研结论与涉及文件，避免重复 read/grep；工具集不含 write/edit，物理上无法写入 |
+| code-reviewer | 只读，不改写：审查前 MUST 先读（若存在），复用其中调研结论与涉及文件，避免重复 read/grep；工具集不含 write/edit，物理上无法写入 |
+
+规则：
+
+- **复用与增量**：开工前复用已记录结论，禁止重复探索；后续轮次只做增量——仅探索未记录的文件/符号/假设，不重复 read/grep 已记录内容。
+- **append-only**：不得改写或删除他人结论。
+- **创建门槛**：提案涉及跨文件或多轮协作时 MUST 创建 scratchpad.md 并写入四阶段骨架；角色专属豁免（不适用本技能编排的场景）只写在各角色模板的「工作边界」节，本技能不复述。
+- **reviewer 关注点回流**：审查员发现的 P0/P1 与关注点写入审查报告，由主 agent 中转回流给可写角色（planner / coder），由其在对应分区 append；审查员不直接写 scratchpad.md。
+- **supersede 权威语义**：识别 `- [R<n> coder] supersede:` 条目，以紧随其后的新结论为权威，旧结论（含旧 `path:line`）不再作为调研或验证依据。
+- **结论与现状不符**：审查员发现 scratchpad.md 结论与代码现状不符时，作为 P0/P1 审查发现发回，不改写。
+
+## 客观判据与两档处置
+
+执行中发现代码现实与 scratchpad.md 记录不一致时，按两档客观判据处置；判据仅为「偏差是否影响任何 task 的前提或产出定义」，禁止主观估量「问题大小」：
+
+- **档一：事实快照过期**——偏差不影响任何 task 的前提或产出定义（纯探索性信息：路径 / 行号 / 符号 / 命令漂移）。处置：继续执行当前任务，不终止；在「实现探索」区 append supersede 修正。
+- **档二：契约动摇**——偏差导致 tasks / proposal / design / specs 的有效性存疑（前提不成立、产出定义变、代码现状与设计决策冲突）。处置：立即停止实现，输出 STATUS: blocked（无 SESSION）并说明冲突点，交由主 agent 裁决（改提案 / 确认「现状即新设计」/ 开新 change）。
+- supersede 标注格式：`- [R<n> coder] supersede: <旧结论摘要>`，随后一行以 `- [R<n> coder]` 标注新结论；两条均落「实现探索」分区，旧结论保留（append-only），不删除。
+- 交付摘要 SUMMARY 义务：本轮发生过 supersede 时，输出格式中的 SUMMARY 行 MUST 提及本次 supersede 清单。
+
+## 与本次任务无关的异常状态（硬栅栏）【无关状态栅栏】
+本节仅适用于 coder（实现类）；reviewer / planner / proposal-reviewer MUST NOT 受本节限制（其职责要求穷尽调查与考古）。
+
+执行中发现异常状态时，按既有客观判据判档——偏差不影响任何 task 的前提或产出定义（判据为否）即属**无关状态**，禁止主观估量「问题大小」。典型无关形态：别人未提交的改动、无关失败测试（无关红测）、无关脏文件、工作树状态与预期不符。
+
+- **前置豁免（最小相关性核查不受限）**：判定「偏差是否影响任何 task 的前提或产出定义」所需的核查（如运行 `git status`、确认被改动文件是否落在本次改动面内）不受本栅栏限制；本栅栏禁止的是**判定为无关之后**的因果考古与因此暂停 task。
+- **硬栅栏**：对判定为无关的状态，MUST NOT 调查——MUST NOT 以 `git log`/`git show`/`git diff`/`git blame` 等手段追查改动来源，MUST NOT 追查「谁改的 / 为何改」，MUST NOT 因该状态暂停当前 task。
+- **处置（显式留痕，不许静默）**：记录为假设 → 写入交付摘要 `SUMMARY` 行 → 继续执行当前任务；缺席的正当行为是问题被显式记录、可审计，而非问题消失。
+- **不吞真阻塞**：本栅栏仅约束无关状态；缺依赖、契约动摇（tasks / proposal / design / specs 有效性存疑，即档二）、权限不足、需用户决策等阻塞本次任务的情形，仍 MUST 立即输出 STATUS: blocked 并附证据，两条判据共存、不互斥。
+- **与既有验证门槛规则一致**：项目级全量校验失败可归因并发 sibling 时，完整动作序列 = 最小相关性核查（含排除自身改动）→ 判定无关 → 附「已排查与本改动无关」证据写入 `SUMMARY` → 继续，不调查改动来源；既有规则的义务不变。
+
+## 评审闭环与轮次上限
+
+严重度：**P0/P1** = 必须修复，阻塞通过；**P2+** = 可选修复，不阻塞通过。
+
+- **Loop 1（Propose → Review）**：planner 完成提案 → proposal-reviewer 审查 → P0/P1 回传主 agent → 委派 planner 修复；往复最多 2 轮。
+- **Loop 2（Code → Review）**：coder 完成（交付前自验证）→ code-reviewer 审阅 + 全局验证 → P0/P1 回传主 agent → 委派 coder 修复；往复上限「最多 3 轮（含首次实现与修复）」，仍无法解决则 STATUS: blocked。
+- **审查员只报告、不改代码**：结论为 APPROVE / REQUEST_CHANGES / BLOCKED；P0/P1 经主 agent 转发给下一轮 coder / planner，审查员不直接改代码、也不改 scratchpad.md。
+- **coder 侧协作流程（三条义务，逐字保持、不弱化）**：
+  - **① 完成实现后**：向主 agent 报告，由主 agent 决定是否委派审查
+  - **② 收到审查反馈（P0/P1）**：反馈统一由 code-reviewer 回传（含全局验证失败）；开工时先把关注点 append 进「代码审查范围」区，用 read/edit/bash 修复后重新标记 ACTION: REVIEW_REQUIRED
+  - **③ 轮次上限**：最多 3 轮（含首次实现与修复）；仍无法解决则 STATUS: blocked
+
+## 报告契约
+
+- **coder**：以固定报告块收尾——`ACTION`（REVIEW_REQUIRED）/ `CHANGE` / `STATUS`（success | partial | blocked）/ `SESSION`（仅 STATUS: blocked 且需 resume 时填写）/ `SUMMARY` / `TASKS` / `FILES`；本轮有 supersede 时 `SUMMARY` 行 MUST 提及 supersede 清单。修复 P0/P1 后输出中增加「本轮修复」章节；需再审时 `ACTION` 仍为 `REVIEW_REQUIRED`。
+- **reviewer（code-reviewer / proposal-reviewer）**：以固定报告块收尾——`结论`（APPROVE / REQUEST_CHANGES / BLOCKED）/ `轮次` / `关键问题`（P0/P1）/ `改进建议`（P2+）；code-reviewer 另附全局验证节。
+- **上报去向**：APPROVE → 报告通过；REQUEST_CHANGES + P0/P1 → 由主 agent 委派对应角色修复；REQUEST_CHANGES + 仅 P2+ → 视为通过，建议可选；BLOCKED → 说明原因，由用户决策。
+- 各角色一律使用各自模板的「输出格式」块收尾；子 agent 无用户，不得采用面向主会话的交互式提问或等待措辞（边界见下节）。
+
+## 生效与兜底
+
+- **注入方式**：本技能经各角色 agent frontmatter 的 `autoloadSkills` 注入——协议技能（本技能）对四个角色**恒在**；coder / planner 各两个技能（本技能 + 一个 openspec 官方技能），两个 reviewer 各一个（仅本技能）。逐角色的精确取值以各自 agent 模板 frontmatter 为单一真源，本节不复述。
+- **兜底指针**：`autoloadSkills` 中的**每个技能各一行** `skill://<name>` 指针（逐行同构、不合并）；技能未自动加载时，用 Skill tool 读取该指针并遵循其流程（协议技能即 `skill://opsx-orchestration-protocol`）。逐角色的精确指针取值以各自模板的「技能」节为单一真源，本节不复述。
+- **技能不可读 → 前提缺失**：角色 `autoloadSkills` 中的技能名不可解析、且用 Skill tool 读取 `skill://<name>` 亦不可读（技能不在场）时，视为前提缺失——输出 `STATUS: blocked`（无 SESSION）并报缺失技能名交由主 agent 决策；MUST NOT 凭记忆复述该技能的流程代替之。
+- **官方技能正文的子 agent 边界**：`openspec-apply-change` / `openspec-propose` 正文面向主会话撰写，对子 agent 的适用面：
+  - **适用**——流程与产物定义：选变更、读 tasks/proposal/design/specs、逐 task 实现、`- [ ]` → `- [x]`、阻塞时不猜测。
+  - **不适用**——子 agent 无用户：`announce` 进度播报（改由本角色模板的「输出格式」块收尾）、「ask the user / 询问用户」、「pause / 等待用户输入」、progress / pause 报告块一律不采用。
+  - 需用户决策的情形仍按 `STATUS: blocked` 上报主 agent，由其决策；报告一律使用各自模板的「输出格式」块。
+- **官方技能文件保持上游原样**：`.omp/skills/openspec-apply-change` / `openspec-propose` MUST NOT 被本插件修改；子 agent 边界只在本节单点声明。