feat(docs): cognitive altitude and proactive scenario extension

Enforce task-language guides for public-user docs, fail function-inventory
quick starts, and require proactive multi-scenario extension when users
raise concrete pain points. Extend docs-audience classifiers and tests.

Author: rockyshi1993

scripts/lib/docs-audience-intent.js

@@ -173,8 +173,73 @@ function classifyDocsAudienceDisambiguationSample(disambiguationText) {
   return 'ok'
 }
 
+/**
+ * Cognitive altitude for public-user guide/readme bodies.
+ * Detects "complete but unreadable" function-inventory quick starts.
+ *
+ * @param {string} body markdown or free text
+ * @param {{ surface?: string }} [opts]
+ * @returns {'ok'|'function-inventory-as-guide'|'concept-dump-no-task'|'ok-reference-dense'|'not-applicable'}
+ */
+function classifyUserDocsCognitiveAltitudeSample(body, opts = {}) {
+  const text = String(body || '')
+  if (!text.trim()) return 'not-applicable'
+
+  const surface = String(opts.surface || 'guide').toLowerCase()
+  const head = text.slice(0, 1200)
+
+  // Identifier-call chains: foo( bar( or a.b.c( density
+  const callLike = (head.match(/\b[A-Za-z_][\w.]*\s*\(/g) || []).length
+  const taskLanguage = /你要|完成|目标是|场景|例如你|第一次|安装后|发一条|创建一个|如何|怎么|步骤\s*[1１一]|推荐路径|适合谁/i.test(head)
+  const conceptOnly = /架构|生命周期|模型|组件|模块|设计|原理/i.test(head) && !taskLanguage && callLike < 2
+
+  if (surface === 'reference') {
+    // Reference may be symbol-dense; still flag pure call lists with zero purpose lines if extreme
+    if (callLike >= 8 && !/用途|何时|用于|use when|purpose/i.test(text) && !taskLanguage) {
+      return 'function-inventory-as-guide'
+    }
+    return 'ok-reference-dense'
+  }
+
+  // guide / readme / quick start
+  if (callLike >= 3 && !taskLanguage) return 'function-inventory-as-guide'
+  // quick-start section that is only chained calls
+  if (/快速开始|quick\s*start|getting started/i.test(head)) {
+    const qs = head.split(/快速开始|quick\s*start|getting started/i)[1] || ''
+    const qsCalls = (qs.slice(0, 500).match(/\b[A-Za-z_][\w.]*\s*\(/g) || []).length
+    if (qsCalls >= 3 && !/安装|install|npm |pnpm |yarn /i.test(qs.slice(0, 500))) {
+      return 'function-inventory-as-guide'
+    }
+  }
+  if (conceptOnly && head.length > 200) return 'concept-dump-no-task'
+  return 'ok'
+}
+
+/**
+ * Whether an assistant reply proactively extended scenarios after a user pain point.
+ * @param {string} userMessage
+ * @param {string} assistantReply
+ * @returns {'ok'|'missing-extension'|'not-applicable'}
+ */
+function classifyProactiveScenarioExtensionSample(userMessage, assistantReply) {
+  const u = String(userMessage || '')
+  const a = String(assistantReply || '')
+  if (!u.trim() || !a.trim()) return 'not-applicable'
+  // User raised a concrete docs/process issue
+  const isPain = /问题|看不懂|复杂|场景|还有|为什么|如何处理|痛点|失败/i.test(u)
+  if (!isPain) return 'not-applicable'
+  // Assistant lists multiple related scenarios (tables, A1/B1, 场景)
+  const extendsScenes = (/场景/.test(a) && (a.match(/场景/g) || []).length >= 2) ||
+    /\|.*场景.*\|/.test(a) ||
+    /A\d|B\d|C\d|同类|延展|还有.*情况|相关失败/i.test(a)
+  if (!extendsScenes) return 'missing-extension'
+  return 'ok'
+}
+
 module.exports = {
   classifyDocsAudienceSample,
   classifyDocsAudienceDriftSample,
-  classifyDocsAudienceDisambiguationSample
+  classifyDocsAudienceDisambiguationSample,
+  classifyUserDocsCognitiveAltitudeSample,
+  classifyProactiveScenarioExtensionSample
 }

scripts/test-docs-audience-intent.js

@@ -5,7 +5,9 @@ const assert = require('assert')
 const {
   classifyDocsAudienceSample,
   classifyDocsAudienceDriftSample,
-  classifyDocsAudienceDisambiguationSample
+  classifyDocsAudienceDisambiguationSample,
+  classifyUserDocsCognitiveAltitudeSample,
+  classifyProactiveScenarioExtensionSample
 } = require('./lib/docs-audience-intent')
 
 // Positive: user guide
@@ -98,4 +100,66 @@ const {
   )
 }
 
+// Cognitive altitude: function inventory as guide
+{
+  const bad = `# 快速开始
+
+createRuntime(opts)
+registerPlugin(p)
+resolveContext(ctx)
+dispatch(event)
+`
+  assert.strictEqual(
+    classifyUserDocsCognitiveAltitudeSample(bad, { surface: 'guide' }),
+    'function-inventory-as-guide'
+  )
+}
+
+// Cognitive altitude: task language ok
+{
+  const good = `# 快速开始
+
+你要完成：用 SDK 发一条消息。
+
+1. 安装依赖 npm i foo
+2. 使用推荐入口 sendMessage
+3. 看到成功回执
+
+深入装配见 Reference。
+`
+  assert.strictEqual(
+    classifyUserDocsCognitiveAltitudeSample(good, { surface: 'guide' }),
+    'ok'
+  )
+}
+
+// Reference may be denser
+{
+  assert.strictEqual(
+    classifyUserDocsCognitiveAltitudeSample(
+      '## sendMessage\n用途：发送消息\nsendMessage(x)\n',
+      { surface: 'reference' }
+    ),
+    'ok-reference-dense'
+  )
+}
+
+// Proactive scenario extension
+{
+  assert.strictEqual(
+    classifyProactiveScenarioExtensionSample(
+      '文档完整但底层函数看不懂怎么办',
+      '除了函数清单，还有这些场景：A1… B1… 同类失败还包括配置字典当使用说明。'
+    ),
+    'ok'
+  )
+  assert.strictEqual(
+    classifyProactiveScenarioExtensionSample(
+      '文档完整但底层函数看不懂怎么办',
+      '可以写得通俗一点。'
+    ),
+    'missing-extension'
+  )
+}
+
 console.log('docs-audience-intent tests passed')

skills/audit-user-manual/SKILL.md

@@ -36,6 +36,7 @@ description: 用户侧文档专项审查聚合入口 — 用于审查最终用
 | 菜单导航 | `SidebarPageRoleMaterializationProbe` / `SidebarGroupSemanticModelProbe`、`pageRoleMatrix`、`sidebarSemanticModel`、route / label 真相源、相邻页面职责、前两组导航是否服务用户主路径 |
 | 受众与渲染顺序 | `DocsAudienceRoleAndRenderedSequenceProbe`：pageRole 分布、首屏前三信息块、前两组 sidebar、current quick start 距离、manual TOC 与 generated outline 重复数 |
 | 内容可懂 | 功能完整性、配置易懂性、术语首次解释、字段/参数/状态/错误解释、示例真实度 |
+| 认知高度 / 任务语言 | guide/readme 是否 Task→Concept；是否函数清单当快速开始；`classifyUserDocsCognitiveAltitudeSample`；唯一推荐路径是否存在；错误是否含恢复 |
 | 专家型产物质量 | `ExpertOutputQualityGate`、`ProductionRecommendedPathGate`、`FrameworkNativeCapabilityFirstGate`、`FixtureBoundaryDisclosureGate`、`AntiPatternContrastGate`、`ExpertEvidenceMatrixGate`，区分生产推荐路径、fixture/mock/demo 边界和反模式 |
 | 真实工作流 | quick start、队列/异步/批处理、导入导出、失败重试、幂等和观测是否是业务主路径；完整声明必须有 `ScenarioCoverageMatrixProbe`，持久化批处理追加 `DurableBatchOrchestrationProbe` |
 | 生成与运行态 | `GeneratedSiteGate`；命中文档站主题、搜索、代码高亮、移动端、暗色/亮色或交互变化时执行 `DocsThemeRuntimeVisualProbeGate` |
@@ -76,4 +77,5 @@ description: 用户侧文档专项审查聚合入口 — 用于审查最终用
 - 禁止把开发契约、数据模型、实现验收、release checklist 或台账状态当作用户文档主路径。
 - 禁止把 fixture、mock、demo、硬编码单例或每个 route 重复声明当作用户主路径的生产推荐实践。
 - 禁止用“章节很多”代替“用户能第一次成功”；必须检查用户任务、配置、失败恢复和下一步。
+- 禁止把「导出函数/类型清单式 quick start」判为用户文档通过；认知高度失败等同主路径失败。
 - 禁止复制 `user-manual-authoring` / `audit-document` / `audit-readme` 的完整长清单；本 Skill 只做聚合入口和输出矩阵。

skills/intent/SKILL.md

@@ -103,7 +103,15 @@ description: 识别用户意图类型（dev/fix/analyze/audit/self-fix/chat/resu
    - `ambiguous` → fail closed，推荐置首  
    - `multi-audience` → 拆任务  
 4. 完成前做受众漂移检查；失败不得宣称文档任务完成。  
-5. 验证：`npm run test:docs-audience`。
+5. 验证：`npm run test:docs-audience`。  
+6. 用户站 guide 完成前须过认知高度：`classifyUserDocsCognitiveAltitudeSample`（禁止 function-inventory-as-guide）。
+
+### 问题驱动场景延展（强制 · PI-20260724-proactive-scenario-extension）
+
+当用户提出**具体痛点/问题**（文档看不懂、流程缺步、规范歧义、某种失败模式等），助手在正面回答之后，**同一轮**须主动延展 3+ 条相关场景或风险（表格或编号），不得只回一句就结束、等用户再问「还有没有其他场景」。
+
+- 机器抽检：`classifyProactiveScenarioExtensionSample(userMessage, assistantReply)` 不得为 `missing-extension`（在适用痛点句上）。  
+- 与 Intent Expansion / C12 同向：扩展是默认义务。
 
 ### HostCapabilityRoutingHandoff
 

skills/spec-governance/gate-registry.json

@@ -17,6 +17,7 @@
     { "id": "base-admission-governance", "ownerSkills": ["spec-absorption", "skill-lifecycle-governance", "test-router"], "trigger": "new or promoted norm skill prompt workflow validator or deployment consumer may affect base path or unrelated intents", "requiredEvidence": ["BaseImpactAssessmentV1", "ComplexityDeltaBudgetV1", "UnaffectedIntentRegression", "replacementOrRetirementCredit", "rollback", "deprecationAndDeletionCondition"], "validationRoute": ["V96"], "legacyAnchors": ["BaseImpactAssessment", "ComplexityDeltaBudget", "UnaffectedIntentRegression"] },
     { "id": "user-manual", "ownerSkills": ["user-manual-authoring"], "trigger": "user manual README quick start or integration guide", "requiredEvidence": ["audience", "taskPath", "configuration", "failureRecovery", "renderedEvidence"], "validationRoute": ["audit-user-manual"], "legacyAnchors": ["UserManualProductizationGate"] },
     { "id": "docs-audience-intent", "ownerSkills": ["user-manual-authoring", "maintainer-docs-site-authoring", "intent", "dev-docs"], "trigger": "write or rewrite project docs site README contributing API reference or vague website docs task", "requiredEvidence": ["docsAudience", "docsSurface", "recommendedAudience", "lockRequired", "driftCheck", "failClosedOnAmbiguous"], "validationRoute": ["test-docs-audience"], "legacyAnchors": ["DocsAudienceIntentGate"] },
+    { "id": "docs-cognitive-altitude", "ownerSkills": ["user-manual-authoring", "audit-user-manual", "readme-authoring", "intent"], "trigger": "public-user guide readme quick start or user complaint that docs are complete but unreadable or too low-level", "requiredEvidence": ["cognitiveAltitude", "taskLanguage", "productionRecommendedPath", "functionInventoryCheck", "proactiveScenarioExtension"], "validationRoute": ["test-docs-audience"], "legacyAnchors": ["UserDocsImmediateComprehensionGate", "UserPerspectiveDocsGate"] },
     { "id": "docs-ia-readability", "ownerSkills": ["user-manual-authoring", "dev-docs", "document-sync"], "trigger": "Chinese user docs sidebar or information architecture", "requiredEvidence": ["pageRole", "sidebarGroup", "renderedSequence", "languageDecision"], "validationRoute": ["GeneratedSiteGate"], "legacyAnchors": ["ChinesePrimaryExpressionGate", "SidebarPageRoleMaterializationProbe"] },
     { "id": "frontend-runtime", "ownerSkills": ["audit-project", "test-router"], "trigger": "runtime page async data cache or user interaction", "requiredEvidence": ["runtimeTarget", "stateMatrix", "networkEvidence", "failureFallback"], "validationRoute": ["browser", "runtime-test"], "legacyAnchors": ["FrontendAsyncCacheRenderGate", "StaleWhileRevalidateGate"] },
     { "id": "release-parity", "ownerSkills": ["audit-release", "release-verification"], "trigger": "push tag release publish or registry topology change", "requiredEvidence": ["candidateDiff", "nativeExitCode", "ciParity", "pack", "registryIdentity"], "validationRoute": ["release-verification"], "legacyAnchors": ["RemoteCIParityPushGate", "NativeCommandExitCodeGate", "ScopedRegistryResolutionGate"] },

skills/user-manual-authoring/SKILL.md

@@ -94,11 +94,48 @@ description: 开源/公开用户站点与最终用户手册写作 Owner — guid
 - `document-sync`：按 `consumerMap`（含 `audience=public-user`）检查当前消费者和部署副本。
 - `DocsAudienceIntentGate`：`scripts/lib/docs-audience-intent.js` + `npm run test:docs-audience`。
 
-## 完成前漂移自检
+## 认知高度与任务语言（L3 · 强制）
+
+> 受众对（public-user）不等于可读。guide/readme 不得做成「完整但全是底层函数」的符号说明书。
+
+### 认知高度三层
+
+| 高度 | 含义 | guide/readme 主路径 | reference |
+|------|------|---------------------|-----------|
+| **Task** | 用户要完成的事、场景、步骤、选择建议 | **必须为主叙事** | 可附「何时用」 |
+| **Concept** | 领域概念、配置含义（白话） | 服务 Task | 可简要 |
+| **Symbol** | 类型名、方法签名、内部模块 | **后置**或链到 reference | 允许密 |
+
+### 写作硬规则
+
+1. **唯一推荐路径**：quick start 只推广一条 `productionRecommendedPath`；底层装配标「高级/扩展」。  
+2. **先任务后符号**：目录与标题优先任务名（「发消息」），不是 `MessageDispatcher`。  
+3. **guide ≠ API inventory**：快速开始若以 ≥3 个未解释的函数调用链为主且无任务句 → **完成失败**。  
+4. **渐进披露**：5 分钟会用 → 30 分钟会选 → 查表 reference；禁止一篇写穿全部 public 函数当使用文档。  
+5. **术语**：内部名首次出现必须白话；配置先默认与选择建议再字段表。  
+6. **reference**：符号可密，每项至少「用途一句话 + 与推荐路径关系/何时不用」。
+
+### 延展失败场景（写作与审查时主动对照）
+
+用户只提一种「看不懂」时，仍应自检相邻风险（问题驱动场景延展）：
+
+| 组 | 场景 |
+|----|------|
+| A 叙事 | 函数清单 guide、概念堆无任务、配置字典、错误码无恢复、多入口无推荐 |
+| B IA | guide/reference 混主路径、源码侧栏、深链才到第一次成功、一篇写穿 |
+| C 示例 | 不可跑、fixture 当生产、无失败路径、版本漂移 |
+| D 伪用户 | 库文档按贡献者写、运维当研发、术语三套 |
+| E 假完整 | TBD、超版承诺、三口径 |
+| F 负担 | 前置未声明、图文不符 |
+| G 元失败 | 受众对高度错、好读但假、单页好整站乱 |
+
+### 完成前漂移自检
 
 - 锁定 `docsAudience=public-user` 后，正文不得以 release checklist / monorepo 内部 / ADR 列表 / 内部台账为**首屏主叙事**。  
-- 机器分类：`classifyDocsAudienceDriftSample('public-user', body)`（`scripts/lib/docs-audience-intent.js`）不得返回 `drift-maintainer-on-user`。  
-- 无安装/第一次成功路径不得宣称用户站完成。
+- `classifyDocsAudienceDriftSample('public-user', body)` 不得为 `drift-maintainer-on-user`。  
+- **`classifyUserDocsCognitiveAltitudeSample(body, { surface })` 不得为 `function-inventory-as-guide` 或 `concept-dump-no-task`**（guide/readme/quick start）。  
+- 无安装/第一次成功路径不得宣称用户站完成。  
+- 验证：`npm run test:docs-audience`。
 
 ## 禁止
 
@@ -109,6 +146,7 @@ description: 开源/公开用户站点与最终用户手册写作 Owner — guid
 - 禁止把当前不可用状态说明冒充目标版本最终用户手册。
 - 禁止把 fixture、mock、demo、硬编码单例或重复 route/middleware/resource 声明写成用户主路径的生产推荐实践；必须标明验证用途和推荐替代。
 - 禁止在单任务内同时写维护者站并宣称双受众完成；多受众须拆任务。
+- **禁止以底层函数/类型调用链作为 quick start 的唯一主叙事**（无任务句、无推荐路径）。
 
 
 ## 同步锚点（validate / consumer）