feat(docs): dual audience authoring and DocsAudienceIntentGate

Add maintainer-docs-site-authoring alongside user-manual-authoring, route
docs work by docsAudience x docsSurface with fail-closed ambiguous and
drift checks, and cover with npm run test:docs-audience. Update dev-docs
handoff, audit-document DA-M, document-sync audience maps, intent
expansion, routing, plugin registration, and gate-registry.

Author: rockyshi1993

changelogs/unreleased.md

@@ -123,3 +123,7 @@ WorkspaceDataAbsorptionScopeGate · DocsSiteVisualAcceptanceGate · OmissionOnly
 - **HomologousDeploy**：`skill-deploy-filter` 同源过滤 gray；作用于 CLI copy 与 `buildDeploymentDescriptors`。
 - **V100** + `npm run test:closure-evidence`。
 - 需求：`.devcodex/devcodex-v1/requirements/控制面闭合证据与误放行治理/`。
+
+## 2026-07-24
+- **[docs-audience]** DocsAudienceIntentGate + user/maintainer site authoring split; 
+pm run test:docs-audience`n

package.json

@@ -66,6 +66,7 @@
     "test:visible-output": "node scripts/test-visible-output-contract.js",
     "test:external-review-claim": "node scripts/test-external-review-claim-verification.js",
     "test:optimization-backlog-evidence": "node scripts/test-optimization-backlog-evidence.js",
+    "test:docs-audience": "node scripts/test-docs-audience-intent.js",
     "test:discipline-execution": "node scripts/test-discipline-execution-probe.js",
     "test:host-instruction-projection": "node scripts/generate-host-instruction-projections.js --check && node scripts/test-host-instruction-projection.js",
     "test:host-adapters": "node scripts/test-host-adapters.js",

plugin.json

@@ -230,6 +230,11 @@
       "file": "skills/user-manual-authoring/SKILL.md",
       "tier": "free"
     },
+    {
+      "id": "maintainer-docs-site-authoring",
+      "file": "skills/maintainer-docs-site-authoring/SKILL.md",
+      "tier": "free"
+    },
     {
       "id": "review-checklist",
       "file": "skills/review-checklist/SKILL.md",

scripts/lib/docs-audience-intent.js

@@ -0,0 +1,180 @@
+'use strict'
+
+/**
+ * DocsAudienceIntentGate classifiers (CP1/CP2: 文档受众双 Skill 分流).
+ * Portable pure functions — no I/O.
+ */
+
+/**
+ * @typedef {'public-user'|'maintainer-dev'|'ambiguous'|'multi-audience'} DocsAudience
+ * @typedef {'guide'|'readme'|'reference'|'migration'|'changelog'|'operations'|'maintainer'|'other'} DocsSurface
+ */
+
+/**
+ * @param {string} prompt
+ * @param {{ pathHints?: string[] }} [opts]
+ * @returns {{
+ *   docsAudience: DocsAudience,
+ *   docsSurface: DocsSurface,
+ *   recommendedAudience: 'public-user'|'maintainer-dev'|null,
+ *   recommendedLabel: string|null,
+ *   signals: string[],
+ *   status: 'ok'|'ambiguous'|'multi-audience',
+ *   failClosed: boolean
+ * }}
+ */
+function classifyDocsAudienceSample(prompt, opts = {}) {
+  const text = String(prompt || '')
+  const pathBlob = (opts.pathHints || []).map(String).join(' ')
+  const blob = `${text}\n${pathBlob}`
+  const signals = []
+
+  const hasUserPhrase = /用户使用|使用文档|安装|quick\s*start|快速开始|接入|给使用者|开源用户|第一次成功|how to use|getting started/i.test(blob)
+  const hasMaintPhrase = /维护者|贡献|contributing|本地开发|clone|发版\s*runbook|release\s*checklist|internals|ADR|开发站点|给维护/i.test(blob)
+  const hasReadme = /\bREADME\b|主入口文档/i.test(blob)
+  const hasReference = /\bAPI\b|CLI|Config\s*参考|接口参考|reference/i.test(blob)
+  const hasMigrationUser = /升级指南|迁移指南|从\s*v?\d|upgrade\s+guide/i.test(blob) && !/实现迁移|迁移代码|写迁移/i.test(blob)
+  const hasMigrationImpl = /实现迁移|迁移代码|写迁移|migration\s+impl/i.test(blob)
+  const hasChangelogUser = /changelog|更新日志|release\s*notes/i.test(blob) && !/发版\s*runbook|发布清单|release\s*checklist/i.test(blob)
+  const hasChangelogMaint = /发版\s*runbook|发布清单|release\s*checklist|tag\s*发布流程/i.test(blob)
+  const hasOpsUser = /自托管|部署方|运维手册|operations/i.test(blob) && !/值班|on-?call|内部\s*runbook/i.test(blob)
+  const hasOpsMaint = /值班|on-?call|内部\s*runbook/i.test(blob)
+  const vagueSiteOnly = /^(?:请)?(?:把|将)?(?:website|文档站|站点文档)(?:写一下|补全|更新)?[.。!！]?$/i.test(text.trim()) ||
+    (/写(?:一下)?(?:website|文档站|站点文档)/i.test(text) && !hasUserPhrase && !hasMaintPhrase && !hasReadme && !hasReference)
+
+  const pathUser = /\/(guide|docs\/intro|getting-started|quick-start)\//i.test(pathBlob)
+  const pathMaint = /\/(contributing|internals|development|maintainer)\//i.test(pathBlob)
+
+  if (hasUserPhrase) signals.push('phrase:public-user')
+  if (hasMaintPhrase) signals.push('phrase:maintainer-dev')
+  if (hasReadme) signals.push('phrase:readme')
+  if (hasReference) signals.push('phrase:reference')
+  if (vagueSiteOnly) signals.push('phrase:vague-site')
+  if (pathUser) signals.push('path:user')
+  if (pathMaint) signals.push('path:maintainer')
+
+  const userHit = hasUserPhrase || hasReadme || hasReference || hasMigrationUser || hasChangelogUser || hasOpsUser || pathUser
+  const maintHit = hasMaintPhrase || hasMigrationImpl || hasChangelogMaint || hasOpsMaint || pathMaint
+
+  if (userHit && maintHit) {
+    return {
+      docsAudience: 'multi-audience',
+      docsSurface: 'other',
+      recommendedAudience: null,
+      recommendedLabel: null,
+      signals,
+      status: 'multi-audience',
+      failClosed: true
+    }
+  }
+
+  if (vagueSiteOnly || (!userHit && !maintHit && /文档站|website|站点文档|写文档/i.test(text))) {
+    const recommendedAudience = pathMaint ? 'maintainer-dev' : (pathUser || hasReadme ? 'public-user' : 'public-user')
+    // path-only vague: still ambiguous if no path; with path can soft-recommend
+    const pureVague = vagueSiteOnly || (!pathUser && !pathMaint && !hasReadme)
+    if (pureVague) {
+      return {
+        docsAudience: 'ambiguous',
+        docsSurface: 'other',
+        recommendedAudience: 'public-user',
+        recommendedLabel: '用户使用站点（安装/接入/排错）（推荐）',
+        signals: signals.length ? signals : ['phrase:vague-docs'],
+        status: 'ambiguous',
+        failClosed: true
+      }
+    }
+  }
+
+  if (maintHit) {
+    let surface = 'maintainer'
+    if (hasMigrationImpl) surface = 'maintainer'
+    if (hasChangelogMaint) surface = 'maintainer'
+    return {
+      docsAudience: 'maintainer-dev',
+      docsSurface: surface,
+      recommendedAudience: null,
+      recommendedLabel: null,
+      signals,
+      status: 'ok',
+      failClosed: false
+    }
+  }
+
+  if (userHit) {
+    let surface = 'guide'
+    if (hasReadme) surface = 'readme'
+    if (hasReference) surface = 'reference'
+    if (hasMigrationUser) surface = 'migration'
+    if (hasChangelogUser) surface = 'changelog'
+    if (hasOpsUser) surface = 'operations'
+    return {
+      docsAudience: 'public-user',
+      docsSurface: surface,
+      recommendedAudience: null,
+      recommendedLabel: null,
+      signals,
+      status: 'ok',
+      failClosed: false
+    }
+  }
+
+  return {
+    docsAudience: 'ambiguous',
+    docsSurface: 'other',
+    recommendedAudience: 'public-user',
+    recommendedLabel: '用户使用站点（安装/接入/排错）（推荐）',
+    signals: signals.length ? signals : ['none'],
+    status: 'ambiguous',
+    failClosed: true
+  }
+}
+
+/**
+ * Detect audience drift in drafted doc body for a locked audience.
+ * @param {'public-user'|'maintainer-dev'} audience
+ * @param {string} body
+ * @returns {'ok'|'drift-maintainer-on-user'|'drift-no-dev-path'|'not-applicable'}
+ */
+function classifyDocsAudienceDriftSample(audience, body) {
+  const text = String(body || '')
+  if (!text.trim()) return 'not-applicable'
+
+  if (audience === 'public-user') {
+    const maintainerPollution = /release\s*checklist|发版清单|monorepo\s*架构|内部台账|ADR\s*列表|contributing\s*流程(?!.*安装)/i.test(text)
+    const hasUserPath = /安装|install|快速开始|quick\s*start|第一次|npm\s+i|pnpm\s+add|yarn\s+add|使用/i.test(text)
+    if (maintainerPollution && !hasUserPath) return 'drift-maintainer-on-user'
+    if (maintainerPollution && /^(?:#|\s)*release\s*checklist/im.test(text.slice(0, 400))) return 'drift-maintainer-on-user'
+    return 'ok'
+  }
+
+  if (audience === 'maintainer-dev') {
+    const hasDevPath = /clone|git\s+clone|npm\s+(?:i|install|test|run)|pnpm|yarn|本地开发|贡献|contributing|环境/i.test(text)
+    const onlyProduct = /这是什么|适合谁|产品价值/.test(text) && !hasDevPath
+    if (onlyProduct || !hasDevPath) return 'drift-no-dev-path'
+    return 'ok'
+  }
+
+  return 'not-applicable'
+}
+
+/**
+ * @param {string} disambiguationText assistant text when status=ambiguous
+ * @returns {'ok'|'missing-recommendation'|'preference-menu'}
+ */
+function classifyDocsAudienceDisambiguationSample(disambiguationText) {
+  const text = String(disambiguationText || '')
+  const hasRecommended = /推荐|（推荐）|\(推荐\)|recommended/i.test(text)
+  const flatMenu = /你希望哪种|选一个|A\s*\/\s*B\s*\/\s*C|A\/B\/C|which would you prefer|pick one of/i.test(text) && !hasRecommended
+  if (flatMenu) return 'preference-menu'
+  if (!/ambiguous|消歧|受众|public-user|maintainer|用户|维护者|推荐/i.test(text)) {
+    return 'missing-recommendation'
+  }
+  if (!hasRecommended) return 'missing-recommendation'
+  return 'ok'
+}
+
+module.exports = {
+  classifyDocsAudienceSample,
+  classifyDocsAudienceDriftSample,
+  classifyDocsAudienceDisambiguationSample
+}

scripts/test-docs-audience-intent.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+'use strict'
+
+const assert = require('assert')
+const {
+  classifyDocsAudienceSample,
+  classifyDocsAudienceDriftSample,
+  classifyDocsAudienceDisambiguationSample
+} = require('./lib/docs-audience-intent')
+
+// Positive: user guide
+{
+  const r = classifyDocsAudienceSample('写开源用户使用文档站，包含安装和快速开始')
+  assert.strictEqual(r.docsAudience, 'public-user')
+  assert.strictEqual(r.status, 'ok')
+  assert.ok(['guide', 'readme'].includes(r.docsSurface) || r.docsSurface === 'guide')
+}
+
+// Positive: reference → public-user
+{
+  const r = classifyDocsAudienceSample('写 API 参考文档和 CLI 说明')
+  assert.strictEqual(r.docsAudience, 'public-user')
+  assert.strictEqual(r.docsSurface, 'reference')
+}
+
+// Positive: maintainer
+{
+  const r = classifyDocsAudienceSample('写维护者开发站点文档，包含 clone、测试与贡献流程')
+  assert.strictEqual(r.docsAudience, 'maintainer-dev')
+  assert.strictEqual(r.status, 'ok')
+}
+
+// Negative 1: vague website → ambiguous + recommended
+{
+  const r = classifyDocsAudienceSample('把 website 写一下')
+  assert.strictEqual(r.docsAudience, 'ambiguous')
+  assert.strictEqual(r.failClosed, true)
+  assert.strictEqual(r.recommendedAudience, 'public-user')
+  assert.ok(r.recommendedLabel && /推荐/.test(r.recommendedLabel))
+}
+
+// Negative 2: user task body polluted with release checklist first screen
+{
+  const drift = classifyDocsAudienceDriftSample(
+    'public-user',
+    '# Release checklist\n\n- tag\n- publish\n\n内部台账状态\n'
+  )
+  assert.strictEqual(drift, 'drift-maintainer-on-user')
+}
+
+// Negative 3: maintainer body without dev path
+{
+  const drift = classifyDocsAudienceDriftSample(
+    'maintainer-dev',
+    '# 产品介绍\n\n这是什么\n适合谁\n产品价值巨大\n'
+  )
+  assert.strictEqual(drift, 'drift-no-dev-path')
+}
+
+// Multi-audience must split
+{
+  const r = classifyDocsAudienceSample('同时写用户使用文档和维护者贡献指南')
+  assert.strictEqual(r.docsAudience, 'multi-audience')
+  assert.strictEqual(r.failClosed, true)
+}
+
+// Disambiguation must carry unique recommendation
+{
+  assert.strictEqual(
+    classifyDocsAudienceDisambiguationSample('受众不明，推荐用户使用站点（推荐），备选维护者开发站'),
+    'ok'
+  )
+  assert.strictEqual(
+    classifyDocsAudienceDisambiguationSample('你希望哪种？A/B/C 选一个'),
+    'preference-menu'
+  )
+}
+
+// Healthy user body ok
+{
+  assert.strictEqual(
+    classifyDocsAudienceDriftSample(
+      'public-user',
+      '# 安装\n\nnpm i foo\n\n## 快速开始\n\n第一次运行…\n'
+    ),
+    'ok'
+  )
+}
+
+// Healthy maintainer body ok
+{
+  assert.strictEqual(
+    classifyDocsAudienceDriftSample(
+      'maintainer-dev',
+      '# 开发\n\ngit clone …\nnpm install\nnpm test\n\n## 贡献\n'
+    ),
+    'ok'
+  )
+}
+
+console.log('docs-audience-intent tests passed')

skills/audit-document/SKILL.md

@@ -59,11 +59,25 @@ description: 通用文档审查维度 DA-1~DA-6 — README/架构文档/开发
 4. 通用结构/准确性问题留在 `DA-*`
 5. 用户路径、快速开始、示例真实度、开发信息后置与消费链一致性问题留在 `RM-*`
 
+## 维护者站点维（DA-M · 条件）
+
+当审查目标为**维护者/贡献者开发文档站**（`docsAudience=maintainer-dev` 或 CONTRIBUTING/dev/internals 主路径）时，在 DA-1~DA-6 之上追加：
+
+| 检查 | 要求 |
+|------|------|
+| DA-M1 可执行 dev 路径 | 具备 clone/环境/依赖安装与 test 或 build 命令之一；不得仅产品介绍 |
+| DA-M2 受众一致 | 主叙事服务维护者；不得伪装成用户安装手册却无用户第一次成功路径 |
+| DA-M3 命令可信 | 关键命令与 `package.json`/仓库脚本不矛盾，或标明 N/A 理由 |
+| DA-M4 漂移 | `classifyDocsAudienceDriftSample('maintainer-dev', body)` 不得为 `drift-no-dev-path` |
+
+用户站审查仍优先 `audit-user-manual`；本维不替代用户站聚合入口。
+
 ## N/A 规则
 
 - 纯图表/示意图文件无受众概念：DA-5 标 N/A
 - 无关联代码：DA-6 标 N/A
 - 未触发用户手册 / 文档站 / 多语言 / 生成站点 / 示例语义 / 专家产物时：对应条件门禁聚合写 `N/A + skipReason`（完整 Gate 名见 registry / Owner Skill）
+- 未触发维护者站：DA-M 聚合 `N/A + skipReason=not-maintainer-docs`
 - 公开主路径若展示旧兼容路径或 DSL/parser 示例：分别检查副作用兼容边界与最小执行探针（Owner：`user-manual-authoring` / `dev-docs`）
 
 

skills/dev-docs/SKILL.md

@@ -6,18 +6,27 @@ description: 文档开发子类型规范 — 技术文档/API文档/README 编
 
 ## 触发条件
 
-用户要求编写/更新文档：README、站点文档、用户使用文档、API 文档、架构文档、开发指南、CHANGELOG、迁移指南等。
+用户要求编写/更新**技术类**文档：API/契约说明、架构文档、开发指南、迁移**实现**说明、通用技术 Markdown 等。
+
+> ⛔ **入口分流（DocsAudienceIntent，强制）**  
+> 写文档任务须先判定 `docsAudience` + `docsSurface`（`scripts/lib/docs-audience-intent.js` / registry `docs-audience-intent`）：  
+> - `public-user`（用户使用站 / README / 用户手册 / 用户向 changelog·operations·reference）→ **必须 handoff** `user-manual-authoring`（+ 条件 `readme-authoring`），**不得**以本 Skill 为主写作入口。  
+> - `maintainer-dev`（维护者开发站 / contributing / 发版 runbook / ADR 站）→ **必须 handoff** `maintainer-docs-site-authoring`。  
+> - `ambiguous` / `multi-audience` → **阻断**；ambiguous 须唯一推荐消歧；multi 须拆任务。  
+> - 仅当受众已是技术读者且 surface 为契约/架构/通用技术文时，本 Skill 才作为主入口（light-api / frontend-api / general-doc）。
 
 ## 豁免项
 
-- 豁免 `plan-review`（文档任务不需要实施计划审查）
+- 豁免 `plan-review`（**业务文档内容**任务不需要实施计划审查）
 - 豁免 `impact-review`（文档变更不涉及代码影响评估）
-- 豁免 CP3（无需实施计划）；必须记录 `CP3: N/A（docs 子类型豁免）`，供 hook/fallback 区分合法豁免与漏确认
-- CP2 简化为**文档大纲确认**（不需要完整技术方案）
+- 豁免 CP3（**仅** `dev.docs` 子类型写业务项目文档时）；必须记录 `CP3: N/A（docs 子类型豁免）`  
+- ⚠️ **控制面 / Skill / 规范包变更**（如本仓库改 skills）走 `dev.default`，**不享受**本豁免  
+- CP2 简化为**文档大纲确认**（业务文档内容任务；控制面任务仍完整技术方案）
 
 ## 目标文档分流
 
-当任务属于“契约驱动型文档”时，优先先冻结目标文档，再让后续实现或联动产物围绕它落地。
+当任务属于“契约驱动型文档”且已锁定为技术契约（非用户站 narrative）时，优先先冻结目标文档，再让后续实现或联动产物围绕它落地。  
+用户侧 **reference** 可由 `user-manual-authoring` **编排** 本 Skill 的 light-api，但 Owner 仍是用户站。
 
 ### 何时视为契约驱动型文档
 
@@ -35,16 +44,15 @@ description: 文档开发子类型规范 — 技术文档/API文档/README 编
 | `frontend-api` | 前端联调、页面/模块接口说明、字段映射说明 | Markdown 前端接口文档 |
 | `general-doc` | 架构文档、开发指南、迁移指南、治理说明、运行手册 | Markdown 通用文档 |
 
-## README 专项写作分支
-
-当目标文档是站点文档、用户使用文档、最终用户使用文档、最终用户手册、README、quick start、接入手册或公开能力页时，优先调用 `user-manual-authoring`，先冻结用户主路径、文档落点和信息架构，再决定是否进入 README 专项分支。
+## README / 用户站 / 维护者站 handoff（强制）
 
-当目标文档是 `README.md` 或承担主使用入口职责的 README / 项目主文档时，在 `user-manual-authoring` 基础上继续调用 `readme-authoring`：
+| 目标 | handoff |
+|------|---------|
+| 用户站、用户手册、README、quick start、接入手册、公开能力页 | **`user-manual-authoring`**（+ 条件 `readme-authoring`） |
+| 维护者开发站、CONTRIBUTING 站区、发版 runbook 主叙事 | **`maintainer-docs-site-authoring`** |
+| light-api / frontend-api / 架构 general-doc（技术读者） | 本 Skill 主入口 |
 
-- 默认第一受众是**用户 / 使用者**
-- 快速开始、常见用法、配置与排错必须早于开发/贡献内容
-- 章节骨架优先使用 `prompts/project-readme.prompt.md`
-- 完成后若需要用户侧文档 review、项目文档审查、菜单导航或信息架构审查，优先叠加 `audit-user-manual`；落点为 README / 主入口文档时再叠加 `audit-readme`
+README 专项仍由 `user-manual-authoring` + `readme-authoring` 承接（默认受众=使用者；开发/贡献后置）。
 
 ## 文档质量标准