kld-sdd 2.6.12 → 2.6.14

package/kld-sdd-guide.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>kld-sdd · 从入门到入土 — SDD 规格驱动开发完整指南</title>
-<meta name="description" content="kld-sdd 完整使用指南：从 SDD 理念、安装初始化，到 11 个 opsx 技能的完整研发工作流。">
+<meta name="description" content="kld-sdd 完整使用指南：13 个可调用 opsx 技能、6 个 TDD 配套包、本体语义闭环、工程知识库与 SkyWalk V3 提效评估。">
 <style>
 /* ─────────────────────────────────────────────────────────
    设计令牌：Terminal × Blueprint
@@ -20,7 +20,7 @@
   --border-soft:#1a2233;
   --text:#e9ecf4;
   --text-2:#a6afc4;
-  --text-3:#6c7690;
+  --text-3:#8993aa;
   --accent:#5eead4;
   --accent-ink:#0a0d14;
   --accent-2:#818cf8;
@@ -65,12 +65,24 @@ body::before{
 a{color:var(--accent);text-decoration:none}
 a:hover{text-decoration:underline}
 code{font-family:var(--mono);font-size:.88em}
+button,a{outline-offset:3px}
+button:focus-visible,a:focus-visible{outline:2px solid var(--accent)}
+.skip-link{
+  position:fixed;left:18px;top:12px;z-index:100;
+  padding:8px 12px;border-radius:8px;background:var(--accent);color:var(--accent-ink);
+  font-family:var(--mono);font-size:.82rem;font-weight:700;transform:translateY(-160%);
+}
+.skip-link:focus{transform:none;text-decoration:none}
+.sr-only{
+  position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;
+  clip:rect(0,0,0,0);white-space:nowrap;border:0;
+}
 
 /* ─────────────────────────────────────────────────────────
    布局骨架
    ───────────────────────────────────────────────────────── */
 .wrap{max-width:var(--maxw);margin:0 auto;padding:0 24px;position:relative;z-index:1}
-section{position:relative;z-index:1;padding:88px 0;border-top:1px solid var(--border-soft)}
+section{position:relative;z-index:1;padding:88px 0;border-top:1px solid var(--border-soft);scroll-margin-top:72px}
 section:first-of-type{border-top:none}
 .sec-head{display:flex;align-items:baseline;gap:18px;margin-bottom:8px;flex-wrap:wrap}
 .sec-num{
@@ -220,13 +232,14 @@ header.nav{
 .stage{
   flex:1 0 auto;min-width:108px;cursor:pointer;text-align:center;
   padding:16px 10px;border-radius:var(--r-md);border:1px solid transparent;
-  transition:all .2s;position:relative;
+  transition:all .2s;position:relative;background:transparent;color:inherit;font:inherit;
+  appearance:none;-webkit-appearance:none;
 }
 .stage:hover{background:var(--surface-2);border-color:var(--border)}
 .stage.active{background:var(--surface-3);border-color:var(--accent);box-shadow:var(--glow)}
 .stage .ic{font-size:1.4rem;margin-bottom:6px;display:block}
-.stage .nm{font-family:var(--mono);font-size:.82rem;font-weight:600;color:var(--text)}
-.stage .rl{font-size:.72rem;color:var(--text-3);margin-top:2px}
+.stage .nm{display:block;font-family:var(--mono);font-size:.82rem;font-weight:600;color:var(--text)}
+.stage .rl{display:block;font-size:.72rem;color:var(--text-3);margin-top:2px}
 .arrow{flex:0 0 auto;display:flex;align-items:center;color:var(--text-3);font-size:1.1rem;padding:0 2px}
 .helpers{display:flex;gap:12px;justify-content:center;margin-top:20px;flex-wrap:wrap}
 .helper{
@@ -276,6 +289,7 @@ header.nav{
   padding:4px 9px;border-radius:6px;cursor:pointer;opacity:0;transition:all .18s;
 }
 .codeblock:hover .copy{opacity:1}
+.codeblock .copy:focus-visible{opacity:1}
 .codeblock .copy:hover{color:var(--accent);border-color:var(--accent)}
 .k-c{color:var(--text-3)} .k-p{color:var(--accent)} .k-s{color:var(--accent-3)} .k-f{color:var(--sky)} .k-o{color:var(--text-2)}
 
@@ -285,6 +299,7 @@ table.tbl thead th{background:var(--surface-2);font-family:var(--mono);font-size
 table.tbl tbody tr:last-child td{border-bottom:none}
 table.tbl tbody tr:hover{background:var(--surface)}
 table.tbl .yes{color:var(--green)} table.tbl .mono{font-family:var(--mono);font-size:.84rem;color:var(--accent)}
+table.tbl caption{text-align:left;color:var(--text-3);font-size:.82rem;margin-bottom:8px}
 
 .tree{
   font-family:var(--mono);font-size:.85rem;line-height:1.9;color:var(--text-2);
@@ -306,6 +321,44 @@ table.tbl .yes{color:var(--green)} table.tbl .mono{font-family:var(--mono);font-
 .step .c .d{color:var(--text-2);font-size:.94rem;margin-top:2px}
 .step .c code{background:var(--surface-2);padding:1px 7px;border-radius:5px;color:var(--accent);font-size:.85rem}
 
+/* 能力概览 / 指标卡 */
+.callout{
+  margin-top:24px;padding:16px 18px;border:1px solid rgba(94,234,212,.28);
+  border-radius:var(--r-md);background:linear-gradient(135deg,rgba(94,234,212,.06),rgba(129,140,248,.04));
+  color:var(--text-2);font-size:.94rem;
+}
+.callout b{color:var(--text)}
+.feature-grid,.metric-grid{
+  display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:16px;margin-top:28px;
+}
+.feature-card,.metric{
+  border:1px solid var(--border);border-radius:var(--r-lg);background:var(--surface);
+  padding:22px 24px;
+}
+.feature-card .eyebrow,.metric .key{
+  font-family:var(--mono);font-size:.72rem;text-transform:uppercase;letter-spacing:.08em;color:var(--accent);
+}
+.feature-card h3,.metric h4{margin:7px 0 8px;font-size:1rem}
+.feature-card p,.metric p{margin:0;color:var(--text-2);font-size:.9rem}
+.metric .value{font-family:var(--mono);font-size:1.18rem;font-weight:700;color:var(--text);margin:5px 0}
+.metric-grid .metric:last-child{grid-column:1/-1}
+.skill-pack-grid{
+  display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:12px;margin-top:20px;
+}
+.skill-pack{
+  border:1px solid var(--border-soft);border-radius:var(--r-md);background:var(--surface);
+  padding:16px 18px;
+}
+.skill-pack code{color:var(--accent);font-size:.8rem}
+.skill-pack p{margin:7px 0 0;color:var(--text-2);font-size:.84rem;line-height:1.55}
+@media (max-width:760px){
+  .feature-grid,.metric-grid{grid-template-columns:1fr}
+  .skill-pack-grid{grid-template-columns:1fr}
+}
+@media (max-width:640px){
+  .hero h1 .dim{display:block;font-size:.72em;margin-top:5px}
+}
+
 /* 双栏角色 */
 .roles{display:grid;grid-template-columns:1fr 1fr;gap:18px;margin-top:30px}
 .role{border:1px solid var(--border);border-radius:var(--r-lg);padding:24px;background:var(--surface)}
@@ -358,6 +411,7 @@ table.tbl .yes{color:var(--green)} table.tbl .mono{font-family:var(--mono);font-
   font-family:var(--sans);font-size:1rem;font-weight:600;padding:18px 22px;cursor:pointer;
   display:flex;justify-content:space-between;align-items:center;gap:14px;
 }
+.faq-q:hover{background:var(--surface-2)}
 .faq-q .chev{color:var(--text-3);transition:transform .2s;flex-shrink:0}
 .faq-item.open .faq-q .chev{transform:rotate(45deg);color:var(--accent)}
 .faq-a{max-height:0;overflow:hidden;transition:max-height .3s ease;color:var(--text-2);font-size:.94rem}
@@ -389,6 +443,7 @@ footer .meta .sep{color:var(--border)}
     background:var(--surface);border-bottom:1px solid var(--border);padding:12px 24px;gap:2px;
   }
 }
+@media (max-width:420px){.nav-cta{display:none}}
 
 /* 窄屏：长内容表格改为可水平滚动，避免撑破 body */
 @media (max-width:720px){
@@ -397,14 +452,21 @@ footer .meta .sep{color:var(--border)}
   .tree{ font-size:.78rem }
 }
 
+@media (hover:none){
+  .codeblock .copy{opacity:1}
+}
+
 @media (prefers-reduced-motion:reduce){
   *{animation:none!important;transition:none!important;scroll-behavior:auto!important}
   .reveal{opacity:1;transform:none}
 }
 </style>
+<noscript><style>.reveal{opacity:1;transform:none}</style></noscript>
 </head>
 <body>
 
+<a class="skip-link" href="#main">跳到正文</a>
+
 <!-- 旅程进度轴 -->
 <div class="journey-rail" aria-hidden="true"><div class="fill" id="railFill"></div></div>
 
@@ -412,34 +474,37 @@ footer .meta .sep{color:var(--border)}
 <header class="nav">
   <div class="wrap nav-inner">
     <div class="brand"><span class="dot"></span><span>kld-sdd</span></div>
-    <nav class="nav-links" id="navLinks">
-      <a href="#why">为什么</a>
+    <nav class="nav-links" id="navLinks" aria-label="页面导航">
       <a href="#install">安装</a>
       <a href="#workflow">工作流</a>
       <a href="#skills">技能</a>
-      <a href="#docs">文档链</a>
-      <a href="#structure">目录</a>
-      <a href="#editors">编辑器</a>
+      <a href="#semantic">语义</a>
+      <a href="#docs">产物</a>
+      <a href="#editors">Agent</a>
+      <a href="#telemetry">度量</a>
       <a href="#faq">FAQ</a>
     </nav>
     <a class="nav-cta" href="#install">开始初始化</a>
-    <button class="menu-btn" id="menuBtn" aria-label="菜单">☰</button>
+    <button type="button" class="menu-btn" id="menuBtn" aria-label="打开页面导航" aria-controls="navLinks" aria-expanded="false">☰</button>
   </div>
 </header>
 
+<main id="main">
+
 <!-- Hero -->
 <section class="hero" id="top">
   <div class="wrap">
-    <div class="tag">规格驱动开发 · 一键部署 SDD 工作流</div>
+    <div class="tag">规格驱动开发 · 语义闭环 · 可度量交付</div>
     <h1>kld-sdd<br><span class="grad">从入门到入土</span> <span class="dim">完整指南</span></h1>
-    <p class="pitch"><b>SDD（Specification-Driven Development）</b>是一种以文档链驱动 AI 编码的研发方法：先写清楚"要做什么"，再让 AI 去实现——避免 AI 乱猜、反复返工。<code>kld-sdd</code> 帮你在项目里一键配好这套工作流所需的全部 AI 技能。</p>
+    <p class="pitch"><b>SDD（Specification-Driven Development）</b>是一种以文档链驱动 AI 编码的研发方法：先写清楚“要做什么”，再让 AI 去实现。<code>kld-sdd</code> 不只部署技能，还把文档转换为可校验的本体事实，并用 SkyWalk V3 追踪交付效率与质量。</p>
     <div class="ctas">
       <a class="btn btn-primary" href="#install">$ npx kld-sdd</a>
       <a class="btn btn-ghost" href="#workflow">查看完整工作流 →</a>
     </div>
     <div class="hero-meta">
       <span>作者：郑浩天</span>
-      <span>更新：2026-07-11</span>
+      <span>能力基线：v2.6.X</span>
+      <span>更新：2026-07-28</span>
     </div>
 
     <div class="term">
@@ -457,15 +522,15 @@ footer .meta .sep{color:var(--border)}
 <span class="o">║     内置 openSpec 标准模版             ║</span><br>
 <span class="o">╚════════════════════════════════════════╝</span><br>
 <span class="o">请选择您使用的 AI 编辑器（按提示选择即可）</span><br>
-<span class="ok">✅ 初始化完成！已部署 11 个 opsx-* skills</span><span class="cursor"></span>
+<span class="ok">✅ 已部署 19 个 skill 目录（13 个入口 + 6 个 TDD 配套）</span><span class="cursor"></span>
       </div>
     </div>
 
     <div class="stats">
-      <div class="stat"><div class="n">10</div><div class="l">opsx skills</div></div>
-      <div class="stat"><div class="n">8</div><div class="l">AI 编辑器</div></div>
-      <div class="stat"><div class="n">4</div><div class="l">文档契约链</div></div>
-      <div class="stat"><div class="n">MIT</div><div class="l">开源协议</div></div>
+      <div class="stat"><div class="n">13+6</div><div class="l">可调用技能 + TDD 配套</div></div>
+      <div class="stat"><div class="n">8</div><div class="l">AI Agent 适配</div></div>
+      <div class="stat"><div class="n">v2</div><div class="l">Ontology Schema</div></div>
+      <div class="stat"><div class="n">V3</div><div class="l">提效评估模型</div></div>
     </div>
   </div>
 </section>
@@ -512,10 +577,11 @@ footer .meta .sep{color:var(--border)}
       <h2 class="sec-title">安装与初始化</h2>
     </div>
     <p class="sec-sub reveal">无需全局安装，进入项目目录后执行 <code>npx kld-sdd</code> 即可。Node.js ≥ 14。</p>
+    <div class="callout reveal"><b>按需部署：</b>交互模式可选择 1 个或全部 8 个 Agent；自动化场景可用 <code>--tool codex</code>、逗号分隔的多选或 <code>--tool all</code>，不会为未选择的 Agent 创建专属目录。</div>
 
     <div class="reveal">
       <div class="codeblock">
-        <button class="copy" data-copy="cd your-project
+        <button type="button" class="copy" data-copy="cd your-project
 npx kld-sdd">复制</button>
 <pre><span class="k-c"># 进入项目目录，一行命令完成初始化</span>
 <span class="k-p">➜</span> <span class="k-s">cd</span> your-project
@@ -523,11 +589,31 @@ npx kld-sdd">复制</button>
       </div>
     </div>
 
+    <div class="reveal" style="margin-top:16px">
+      <div class="codeblock">
+        <button class="copy" type="button" data-copy="npx kld-sdd --tool codex
+npx kld-sdd --tool cursor,claude
+npx kld-sdd --tool all
+npx kld-sdd --skip-openspec
+npx kld-sdd --skip-template
+npx kld-sdd --help
+npx kld-sdd --version">复制</button>
+<pre><span class="k-c"># 常用非交互选项</span>
+<span class="k-p">➜</span> <span class="k-s">npx</span> <span class="k-f">kld-sdd</span> --tool codex
+<span class="k-p">➜</span> <span class="k-s">npx</span> <span class="k-f">kld-sdd</span> --tool cursor,claude
+<span class="k-p">➜</span> <span class="k-s">npx</span> <span class="k-f">kld-sdd</span> --tool all
+<span class="k-p">➜</span> <span class="k-s">npx</span> <span class="k-f">kld-sdd</span> --skip-openspec
+<span class="k-p">➜</span> <span class="k-s">npx</span> <span class="k-f">kld-sdd</span> --skip-template  <span class="k-c"># 跳过 skills、运行时与手册部署</span>
+<span class="k-p">➜</span> <span class="k-s">npx</span> <span class="k-f">kld-sdd</span> --help
+<span class="k-p">➜</span> <span class="k-s">npx</span> <span class="k-f">kld-sdd</span> --version</pre>
+      </div>
+    </div>
+
     <div class="steps">
       <div class="step reveal"><div class="n">1</div><div class="c"><b>选择编辑器</b><div class="d">运行 <code>npx kld-sdd</code> 后，按交互提示选择你使用的 AI 编辑器（如 Cursor、Claude Code、昆仑智码等）即可。</div></div></div>
-      <div class="step reveal"><div class="n">2</div><div class="c"><b>运行 openspec init</b><div class="d">自动检测并安装 <code>@fission-ai/openspec</code>，生成变更目录结构。</div></div></div>
-      <div class="step reveal"><div class="n">3</div><div class="c"><b>部署 opsx skills</b><div class="d">扁平一层部署到 <code>.*/skills/opsx-*/</code>，清理原生 openspec 命令与旧版嵌套 bundle。</div></div></div>
-      <div class="step reveal"><div class="n">4</div><div class="c"><b>部署遥测与门禁</b><div class="d">部署 <code>skywalk-sdd/log.cjs</code>、Git hooks 质量门禁、CI 兜底模板（仅 Git 项目），并初始化全局 <code>overview.md</code>。</div></div></div>
+      <div class="step reveal"><div class="n">2</div><div class="c"><b>运行 openspec init</b><div class="d">先检测 <code>@fission-ai/openspec</code>；缺失时询问是否安装，确认后生成变更目录结构。</div></div></div>
+      <div class="step reveal"><div class="n">3</div><div class="c"><b>部署 19 个 skill 目录</b><div class="d">13 个可调用入口 + 6 个 TDD 配套包，扁平部署到所选 Agent 的 <code>skills/opsx-*/</code>，同时清理旧版嵌套 bundle。</div></div></div>
+      <div class="step reveal"><div class="n">4</div><div class="c"><b>部署语义、度量与门禁运行时</b><div class="d">部署 <code>log.cjs</code>、<code>metrics-v3.cjs</code>、<code>context-client.cjs</code>、<code>ontology/</code>、Git/CI 门禁模板，以及 Claude/CodeBuddy 专属 Hook Pack。</div></div></div>
       <div class="step reveal"><div class="n">5</div><div class="c"><b>更新 .gitignore</b><div class="d">自动忽略个人配置、telemetry 数据、worktree 临时目录。</div></div></div>
     </div>
   </div>
@@ -540,39 +626,41 @@ npx kld-sdd">复制</button>
       <span class="sec-num">§ 2</span>
       <h2 class="sec-title">核心工作流</h2>
     </div>
-    <p class="sec-sub reveal">8 个阶段技能按顺序串成文档链 → 代码链 → 归档链。点击下方任一阶段，跳转查看详情。</p>
+    <p class="sec-sub reveal">8 个阶段技能按顺序串成文档链 → 代码链 → 归档链；5 个辅助入口贯穿检索、规则和知识闭环。点击任一阶段可跳转到详情。</p>
 
     <div class="pipeline reveal">
       <div class="pipeline-hint">▼ 点击阶段查看详解 ▼</div>
       <div class="flow" id="flow">
-        <div class="stage" data-target="sk-propose"><span class="ic">🎯</span><div class="nm">propose</div><div class="rl">Why</div></div>
+        <button class="stage" type="button" data-target="sk-propose"><span class="ic">🎯</span><span class="nm">propose</span><span class="rl">Why</span></button>
         <span class="arrow">→</span>
-        <div class="stage" data-target="sk-spec"><span class="ic">📐</span><div class="nm">spec</div><div class="rl">What</div></div>
+        <button class="stage" type="button" data-target="sk-spec"><span class="ic">📐</span><span class="nm">spec</span><span class="rl">What</span></button>
         <span class="arrow">→</span>
-        <div class="stage" data-target="sk-design"><span class="ic">🏗️</span><div class="nm">design</div><div class="rl">How</div></div>
+        <button class="stage" type="button" data-target="sk-design"><span class="ic">🏗️</span><span class="nm">design</span><span class="rl">How</span></button>
         <span class="arrow">→</span>
-        <div class="stage" data-target="sk-task"><span class="ic">🧩</span><div class="nm">task</div><div class="rl">Do</div></div>
+        <button class="stage" type="button" data-target="sk-task"><span class="ic">🧩</span><span class="nm">task</span><span class="rl">Do</span></button>
         <span class="arrow">→</span>
-        <div class="stage" data-target="sk-check"><span class="ic">🔍</span><div class="nm">check</div><div class="rl">Verify</div></div>
+        <button class="stage" type="button" data-target="sk-check"><span class="ic">🔍</span><span class="nm">check</span><span class="rl">Verify</span></button>
         <span class="arrow">→</span>
-        <div class="stage" data-target="sk-apply"><span class="ic">⚡</span><div class="nm">apply</div><div class="rl">Apply</div></div>
+        <button class="stage" type="button" data-target="sk-apply"><span class="ic">⚡</span><span class="nm">apply</span><span class="rl">Apply</span></button>
         <span class="arrow">→</span>
-        <div class="stage" data-target="sk-test"><span class="ic">🧪</span><div class="nm">test</div><div class="rl">Test</div></div>
+        <button class="stage" type="button" data-target="sk-test"><span class="ic">🧪</span><span class="nm">test</span><span class="rl">Test</span></button>
         <span class="arrow">→</span>
-        <div class="stage" data-target="sk-archive"><span class="ic">📦</span><div class="nm">archive</div><div class="rl">Archive</div></div>
+        <button class="stage" type="button" data-target="sk-archive"><span class="ic">📦</span><span class="nm">archive</span><span class="rl">Archive</span></button>
       </div>
       <div class="helpers">
         <span class="helper"><span class="ic">🧭</span> opsx-explore · 浏览变更状态</span>
         <span class="helper"><span class="ic">📚</span> opsx-knowledge · 业务知识库检索</span>
         <span class="helper"><span class="ic">📜</span> opsx-rules · 生成/更新 Agent 规则</span>
+        <span class="helper"><span class="ic">🔗</span> opsx-ontology-query · 工程 KB 查询</span>
+        <span class="helper"><span class="ic">⬆️</span> opsx-kb-ingest · Archive 入库</span>
       </div>
     </div>
 
     <div class="steps" style="margin-top:36px">
-      <div class="step reveal"><div class="n">A</div><div class="c"><b>文档链（规划）</b><div class="d"><code>propose → spec → design → task</code> 把需求逐步精化为可执行契约，每步产出一份 markdown。</div></div></div>
-      <div class="step reveal"><div class="n">B</div><div class="c"><b>门禁（验证）</b><div class="d"><code>check</code> 在写代码前验证文档链的完整性/一致性/可执行性——只读检查，不修改文档。</div></div></div>
+      <div class="step reveal"><div class="n">A</div><div class="c"><b>文档链（规划）</b><div class="d"><code>propose → spec → design → task</code> 把需求逐步精化为可执行契约；每次写入后立即对账为 draft 工作态本体。</div></div></div>
+      <div class="step reveal"><div class="n">B</div><div class="c"><b>门禁（验证）</b><div class="d"><code>check</code> 对原始文档做只读检查，同时全量重建可再生的本体 JSON，验证 STMT → AC → DES → TASK 追溯链。</div></div></div>
       <div class="step reveal"><div class="n">C</div><div class="c"><b>实施链（执行）</b><div class="d"><code>apply → test</code> 按 DAG 依赖顺序逐任务实现，编译/测试门禁逐任务拦截，实时更新 tasks.md。</div></div></div>
-      <div class="step reveal"><div class="n">D</div><div class="c"><b>归档（收口）</b><div class="d"><code>archive</code> 真实移入 archive 目录，同步正式 specs，生成最终中文度量报告（md+html）。</div></div></div>
+      <div class="step reveal"><div class="n">D</div><div class="c"><b>归档（收口）</b><div class="d"><code>archive</code> 真实移入 archive 目录，同步正式 specs，基于 V3 Report Model 生成最终中文度量报告（md+html+json）。</div></div></div>
     </div>
   </div>
 </section>
@@ -582,32 +670,33 @@ npx kld-sdd">复制</button>
   <div class="wrap">
     <div class="sec-head reveal">
       <span class="sec-num">§ 3</span>
-      <h2 class="sec-title">11 个技能详解</h2>
+      <h2 class="sec-title">13 个可调用技能 + 6 个 TDD 配套包</h2>
     </div>
-    <p class="sec-sub reveal">初始化后部署为扁平一层：<code>.claude/skills/opsx-*/SKILL.md</code> → 激活即用 <code>/opsx-propose</code>。</p>
+    <p class="sec-sub reveal">8 个阶段入口 + 5 个辅助/知识入口组成可调用层；另有 6 个 <code>opsx-tdd-*</code> 配套包被主流程按需引用，不进入斜杠命令清单。所有目录都以扁平一层部署到所选 Agent。</p>
+    <div class="callout reveal"><b>为什么是 13 + 6：</b><code>OPSX_SKILL_DIRS</code> 定义 13 个命令元数据；初始化会复制模板目录中的全部 19 个 skill 目录。KunlunZhima 为 13 个入口生成 command bridge，其余 6 个只作为 TDD 规则与检查依赖。</div>
 
     <div class="skills-grid">
       <div class="skill reveal" id="sk-propose" style="border-left-color:#5eead4">
         <div class="top"><span class="idx">01</span><h3>opsx-propose <span class="arg">&lt;变更名称&gt;</span></h3><span class="role">Why · 业务意图</span></div>
-        <p>创建业务意图文档，明确"为什么要做这件事"。把产品需求转化为结构化的业务意图文档。</p>
-        <p>没说清楚时，AI 会主动问 4 个问题：<b>痛点 / 目标 / 影响模块 / 约束</b>，并推导出 kebab-case 变更名（如 <code>add-user-auth</code>），生成 propose.md 后展示摘要让你确认。</p>
-        <div class="out">openspec/changes/&lt;name&gt;/propose.md</div>
+        <p>创建业务意图文档，明确“为什么做”。除痛点、目标、影响模块与约束外，还会让你确认 <b>Full / Simple 模式、测试策略和 change-type</b>（config / document / report / composite / other），并写入稳定的 <code>change-id</code>。</p>
+        <p>若提供 REQ / FEAT 外部编号，会通过 <code>opsx-ontology-query</code> 做 Continuity 查询，识别新增、延续或迭代能力；不会把本地 archive 当成跨迭代权威。</p>
+        <div class="out">proposal.md + artifacts/proposal.ontology.json + ontology/working-ontology.json</div>
       </div>
 
       <div class="skill reveal" id="sk-spec" style="border-left-color:#38bdf8">
         <div class="top"><span class="idx">02</span><h3>opsx-spec <span class="arg">&lt;变更名称&gt;</span></h3><span class="role">What · 技术契约</span></div>
         <p>创建技术契约文档，明确"要实现什么 API 和规范"。<b>这是代码生成的唯一依据，必须精确无歧义。</b></p>
-        <p>读取 propose.md，发现模糊描述时主动追问（如"高性能" → 具体 QPS/RT 是多少？），确认 API 范围、性能指标、安全要求后生成 spec.md。</p>
+        <p>读取 proposal.md，发现模糊描述时主动追问（如“高性能” → 具体 QPS/RT 是多少？），确认 API 范围、性能指标与安全要求；场景写入稳定 STMT / AC 身份和可选 <code>external-ref</code>。</p>
         <div class="red"><b>质量红线：</b>所有参数有类型、必填标记、范围约束、示例值；性能指标是具体数字（如 <code>&lt; 100ms P99</code>）；边界场景覆盖正常流程 + 所有异常流程。</div>
-        <div class="out">openspec/changes/&lt;name&gt;/specs/&lt;capability&gt;/spec.md</div>
+        <div class="out">Full: specs/&lt;capability&gt;/spec.md；Simple: spec.md；同步 spec.ontology.json</div>
       </div>
 
       <div class="skill reveal" id="sk-design" style="border-left-color:#60a5fa">
         <div class="top"><span class="idx">03</span><h3>opsx-design <span class="arg">&lt;变更名称&gt;</span></h3><span class="role">How · 实现方案</span></div>
-        <p>创建技术实现方案，明确"怎么做"——聚焦本业务，不写全局架构。读取 propose + spec，分析约束和设计难点；存在多种方案时列出让你选择。</p>
+        <p>创建技术实现方案，明确“怎么做”——聚焦本业务，不写全局架构。读取 proposal + spec，分析约束和设计难点；存在多种方案时列出让你选择。</p>
         <div class="red"><b>质量红线：</b>不写全局中间件或框架选型（那是项目级的事）；接口调用明确到具体接口名和调用方式；数据库表结构到字段级别（类型、长度、索引）。</div>
         <p>产出包含：时序图、模块设计、数据表结构、异常处理。</p>
-        <div class="out">openspec/changes/&lt;name&gt;/specs/&lt;capability&gt;/design.md</div>
+        <div class="out">design.md + design.ontology.json（DES realizes STMT）</div>
       </div>
 
       <div class="skill reveal" id="sk-task" style="border-left-color:#818cf8">
@@ -615,7 +704,7 @@ npx kld-sdd">复制</button>
         <p>将 design.md 拆解为 AI 可执行的原子任务列表。<b>每个任务的标准：AI 能在 5 分钟内完成。</b></p>
         <p>统计需要覆盖的实现点（API 数、模块数、数据表数），预估任务总数并确认拆解策略；发现循环依赖、复杂算法等风险时主动告知。</p>
         <div class="red"><b>质量红线：</b>100% 覆盖 spec 的每个 API 和约束；100% 覆盖 design 的每个模块和接口；每个任务有明确验收标准和单测要求。</div>
-        <div class="out">openspec/changes/&lt;name&gt;/specs/&lt;capability&gt;/tasks.md</div>
+        <div class="out">tasks.md + tasks.ontology.json（TASK implements / covers / dependsOn）</div>
       </div>
 
       <div class="skill reveal" id="sk-check" style="border-left-color:#a78bfa">
@@ -626,9 +715,10 @@ npx kld-sdd">复制</button>
           <li><b>一致性</b>：spec 的 API 在 design 中是否有对应方案；字段命名是否一致</li>
           <li><b>算法正确性</b>：数据流转无矛盾，异常覆盖边界，性能满足 spec 约束</li>
           <li><b>可执行性</b>：每个任务 ≤ 5 分钟，DAG 无循环依赖，代码锚点存在</li>
+          <li><b>语义追溯</b>：全量 reconcile 后验证 STMT → AC → DES → TASK、外部编号与身份版本链</li>
         </ul>
-        <p>Check 是<b>只读检查</b>，不修改任何文档；发现问题时列出严重问题和警告，并推荐修复命令（不自动执行）。</p>
-        <div class="out">结构化检查报告（通过 / 警告 / 失败）+ 修复建议</div>
+        <p>Check 不修改 proposal/spec/design/tasks 原文，但会原子刷新可再生的本体 JSON。检查结果记录 reviewer 独立性：跨会话独立评审的 Q3 可标为 <code>verified</code>，自评则为 <code>provisional</code>。</p>
+        <div class="out">结构化检查结果 + pending 本体 revision + 修复建议</div>
       </div>
 
       <div class="skill reveal" id="sk-apply" style="border-left-color:#c084fc">
@@ -639,6 +729,7 @@ npx kld-sdd">复制</button>
           <li><b>隔离红线</b>：⛔ 禁止加载同级其他 Capability 的文档</li>
           <li><b>DAG 依赖拦截</b>：前置任务未完成则拦截，同层独立任务可并行派发子代理</li>
           <li><b>逐任务门禁</b>：每完成一个任务，编译检查 + 测试门禁必须通过，立即更新 tasks.md checkbox</li>
+          <li><b>TDD 纪律包</b>：当 <code>test-strategy=tdd</code> 时加载 core / rules / quality / anti-patterns / review</li>
           <li><b>可选 worktree 并行</b>：解耦的 capability 各自 worktree 加速，做完按依赖合并回集成分支</li>
         </ul>
         <div class="red"><b>Git 只读策略：</b>禁止为度量自动 <code>git init/add/commit</code> 或创建分支；非 Git 项目用 <code>vcs_mode=no-git</code> 继续执行，不得中断。</div>
@@ -653,20 +744,21 @@ npx kld-sdd">复制</button>
           <li><code>impl-first</code> → 警告：强制补跑测试</li>
           <li><code>none</code> → 跳过</li>
         </ul>
-        <p>Claude Code 的 <code>sdd-apply-test-gate.cjs</code> 会在 <code>log.cjs end</code>、worktree 收尾、会话 Stop 时自动校验——无真实测试证据则阻断。</p>
+        <p>Claude Code 与 CodeBuddy 的 Hook Pack 会在阶段结束、worktree 收尾或会话停止时校验真实测试证据；其他 Agent 由 Skill 自检和 Git/CI 证据门禁兜底。</p>
         <div class="out">测试执行结果 + telemetry 证据（非占位数据）</div>
       </div>
 
       <div class="skill reveal" id="sk-archive" style="border-left-color:#d8b4fe">
         <div class="top"><span class="idx">08</span><h3>opsx-archive <span class="arg">&lt;变更名称&gt;</span></h3><span class="role">Archive · 归档收口</span></div>
-        <p>安全结束变更生命周期：真实归档文档、同步正式 specs、记录 archive telemetry，并生成最终中文度量报告。</p>
+        <p>通过两阶段事务安全结束变更生命周期：先在 staging 重新解析与校验，成功后才切换正式 archive；同步正式 specs、确认本体快照并生成度量报告。</p>
         <ul class="tight">
           <li>询问归档原因：已完成 / 取消 / 搁置 / 其他</li>
-          <li>运行 <code>doctor</code> 自检，<code>severe_issues</code> 阻断归档</li>
+          <li>运行 <code>doctor</code>、<code>semantic-reconcile</code> 与 <code>semantic-check</code>，阻断严重问题</li>
           <li>扫描 tasks 完成状态，未勾选项写入报告（不阻断归档）</li>
-          <li>一步执行 <code>archive-docs</code>：移动目录 + 同步 specs + 生成报告</li>
+          <li>生成 confirmed snapshot、canonical facts、manifest、conversion report 与相邻 zip 包</li>
+          <li>加载 <code>opsx-kb-ingest</code> 上传 Archive Package，成功后写入入库回执</li>
         </ul>
-        <div class="out">archive/&lt;日期&gt;-&lt;name&gt;/ + report.md + report.html + execution-log.md</div>
+        <div class="out">archive/&lt;日期&gt;-&lt;name&gt;/reports/&lt;name&gt;-report.{md,html,json} + logs/execution-log.md + 相邻 &lt;日期&gt;-&lt;name&gt;.zip</div>
       </div>
 
       <div class="skill reveal" id="sk-explore" style="border-left-color:#5eead4">
@@ -686,7 +778,92 @@ npx kld-sdd">复制</button>
         <p>扫描项目结构后，为已部署的 Agent 生成 5 主题规则（架构/编码/测试/数据安全/Git 提交），或对比现有规则输出更新建议。各 Agent 规则位置与格式不同（.md / .mdc），skill 按落位矩阵自动写入。</p>
         <div class="out">按 Agent 落位的规则文件 + 更新建议表</div>
       </div>
+
+      <div class="skill reveal" id="sk-ontology-query" style="border-left-color:#38bdf8">
+        <div class="top"><span class="idx">12</span><h3>opsx-ontology-query</h3><span class="role">依赖 · 工程知识查询</span></div>
+        <p>通过 API Key 查询 Engineering KB 的本体事实，支持上下文检索、外部需求号解析、Spec 复用、实体详情、一跳结构与多跳影响分析。<code>propose</code> 与 <code>spec</code> 将它作为 Continuity / 场景身份的硬依赖。</p>
+        <p>首次使用会引导选择 Space 与知识库，并把密钥和目标写入 gitignored 的 <code>.local/state.json</code>；无命中时明确返回“无当前依据”，不会编造 UUID 或事实。</p>
+        <div class="out">带引用的工程事实、复用包、身份解析或影响分析</div>
+      </div>
+
+      <div class="skill reveal" id="sk-kb-ingest" style="border-left-color:#818cf8">
+        <div class="top"><span class="idx">13</span><h3>opsx-kb-ingest</h3><span class="role">依赖 · Archive 入库</span></div>
+        <p>通过 API Key 将归档 zip 上传到 Engineering KB，支持上传、任务状态、任务列表与失败重试。上传前校验 manifest、canonical facts、SHA-256、外部编号作用域与 project/space 身份。</p>
+        <p>同一 <code>archive_id + content_hash</code> 幂等；冲突或编号不合法时整包回滚，并引导回到 kld-sdd 修正，而不是在知识库里现场改绑。</p>
+        <div class="out">入库 Job 结果 + ingest-receipt.json（归档流程成功时）</div>
+      </div>
+    </div>
+
+    <div class="callout reveal"><b>6 个 TDD 配套包不会单独出现在命令菜单：</b>它们随 13 个入口一起部署，由 <code>propose/task/check/apply/test</code> 根据测试策略渐进加载，避免每次把整套测试规则塞进上下文。</div>
+    <div class="skill-pack-grid">
+      <div class="skill-pack reveal"><code>opsx-tdd-core</code><p>红 → 绿 → 重构铁律、执行门禁与完成自检。</p></div>
+      <div class="skill-pack reveal"><code>opsx-tdd-rules</code><p>DAG、Controller 策略、任务类型与测试证据规则库。</p></div>
+      <div class="skill-pack reveal"><code>opsx-tdd-quality</code><p>Mock 边界、命名、Given-When-Then 与语言模板。</p></div>
+      <div class="skill-pack reveal"><code>opsx-tdd-anti-patterns</code><p>RED/GREEN 阶段 16 类测试反模式检测与修复。</p></div>
+      <div class="skill-pack reveal"><code>opsx-tdd-review</code><p>独立审查测试是否真正覆盖关键行为和异常路径。</p></div>
+      <div class="skill-pack reveal"><code>opsx-tdd-metrics</code><p>按需量化隔离、命名、可测试性与覆盖率缺口。</p></div>
+    </div>
+  </div>
+</section>
+
+<!-- 本体语义闭环 -->
+<section id="semantic">
+  <div class="wrap">
+    <div class="sec-head reveal">
+      <span class="sec-num">§ 4</span>
+      <h2 class="sec-title">本体语义与工程知识闭环</h2>
+    </div>
+    <p class="sec-sub reveal">Markdown 仍是人类可读的事实源；Ontology v2 把 Change、Capability、STMT、AC、Constraint、Design、Task、Artifact、DocumentSection 与 OntologySnapshot 物化为稳定身份、版本链和显式关系，让 Check 能确定性验证、Archive 能安全入库。</p>
+
+    <div class="feature-grid">
+      <article class="feature-card reveal">
+        <div class="eyebrow">Identity</div>
+        <h3>人工锚点 + 双层 UUID 版本身份</h3>
+        <p><code>CHG/CAP/STMT/AC/CON/DES/TASK</code> 便于人读；<code>entity-id</code> 跨迭代复用，<code>version-id</code> 随修改演进，<code>predecessor-version</code> 阻止版本断链与分叉。</p>
+      </article>
+      <article class="feature-card reveal">
+        <div class="eyebrow">Materialize</div>
+        <h3>写完即生成工作态事实</h3>
+        <p>propose/spec/design/task 每次写入后立即 reconcile，产出 <code>artifacts/**/*.ontology.json</code>、<code>ontology/artifact-index.json</code> 与 <code>ontology/working-ontology.json</code>，状态为 draft/pending，尚不能直接入库。</p>
+      </article>
+      <article class="feature-card reveal">
+        <div class="eyebrow">Traceability</div>
+        <h3>跨文档关系可计算</h3>
+        <p><code>CHG contains CAP → STMT acceptedBy AC → DES realizes STMT → TASK implements/covers DES/STMT</code>；Task DAG、悬空引用、重号和外部编号作用域都可被门禁检查。</p>
+      </article>
+      <article class="feature-card reveal">
+        <div class="eyebrow">Archive Package</div>
+        <h3>confirmed 快照 → 知识库</h3>
+        <p>Archive 两阶段事务生成 <code>archive-ontology.json</code>、<code>canonical-facts.json</code>、转换报告、manifest 与 SHA-256 zip；随后由 <code>opsx-kb-ingest</code> 幂等入库。</p>
+      </article>
+    </div>
+
+    <div class="callout reveal"><b>跨迭代真相源：</b>历史身份和可复用 Spec 以 Engineering KB current facts 为准；<code>opsx-ontology-query</code> 负责 Continuity、复用和影响查询。消费方不得扫描本地 <code>archive/</code> 后自行复制 UUID。</div>
+
+    <div class="codeblock reveal">
+      <button class="copy" type="button" data-copy="node skywalk-sdd/log.cjs semantic-identity --delta-state=added
+node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=add-user-auth
+node skywalk-sdd/log.cjs semantic-check --project=. --change=add-user-auth --profile=full
+node skywalk-sdd/log.cjs semantic-status --project=. --change=add-user-auth
+node skywalk-sdd/log.cjs semantic-observe --project=. --change=add-user-auth">复制</button>
+<pre><span class="k-c"># 身份、对账、门禁与状态</span>
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">semantic-identity</span> --delta-state=added
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">semantic-reconcile</span> --project=. --change=add-user-auth
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">semantic-check</span> --project=. --change=add-user-auth --profile=full
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">semantic-status</span> --project=. --change=add-user-auth
+<span class="k-c"># observe 只是可选同步优化，不替代 Check / Archive 的全量对账</span>
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">semantic-observe</span> --project=. --change=add-user-auth</pre>
     </div>
+
+    <table class="tbl reveal">
+      <caption>语义校验 profile（<code>auto</code> 会从 proposal 的 mode 推断）</caption>
+      <thead><tr><th scope="col">Profile</th><th scope="col">适用形态</th><th scope="col">阻断重点</th></tr></thead>
+      <tbody>
+        <tr><td class="mono">simple</td><td>单能力、轻量变更</td><td>强制 STMT → AC；Design/Task 不存在时跳过</td></tr>
+        <tr><td class="mono">full</td><td>多 Capability 完整链</td><td>强制 STMT → AC → DES → TASK 全链与 Task DAG</td></tr>
+        <tr><td class="mono">strict</td><td>高可信归档</td><td>在 full 基础上要求完整语义来源与身份连续性</td></tr>
+      </tbody>
+    </table>
   </div>
 </section>
 
@@ -694,24 +871,26 @@ npx kld-sdd">复制</button>
 <section id="docs">
   <div class="wrap">
     <div class="sec-head reveal">
-      <span class="sec-num">§ 4</span>
+      <span class="sec-num">§ 5</span>
       <h2 class="sec-title">文档链与产物</h2>
     </div>
-    <p class="sec-sub reveal">每个阶段都有明确的输入与产出，形成可追溯的文档→代码→报告链。</p>
+    <p class="sec-sub reveal">每个阶段都有明确输入、人工可读产物与可再生语义产物，最终形成文档 → 本体 → 代码 → 报告 → 知识库的闭环。</p>
 
     <table class="tbl reveal">
-      <thead><tr><th>阶段</th><th>回答</th><th>输入</th><th>产出</th></tr></thead>
+      <caption>核心生命周期的输入与主要产物</caption>
+      <thead><tr><th scope="col">阶段</th><th scope="col">回答</th><th scope="col">输入</th><th scope="col">产出</th></tr></thead>
       <tbody>
-        <tr><td class="mono">propose</td><td>Why</td><td>产品需求</td><td class="mono">propose.md</td></tr>
-        <tr><td class="mono">spec</td><td>What</td><td class="mono">propose.md</td><td class="mono">spec.md</td></tr>
-        <tr><td class="mono">design</td><td>How</td><td class="mono">propose + spec</td><td class="mono">design.md</td></tr>
+        <tr><td class="mono">propose</td><td>Why</td><td>产品需求 + Continuity</td><td class="mono">proposal.md + proposal.ontology.json</td></tr>
+        <tr><td class="mono">spec</td><td>What</td><td class="mono">proposal.md + KB context</td><td class="mono">spec.md + spec.ontology.json</td></tr>
+        <tr><td class="mono">design</td><td>How</td><td class="mono">proposal + spec + overview</td><td class="mono">design.md + design.ontology.json</td></tr>
         <tr><td class="mono">task</td><td>Do</td><td class="mono">design.md</td><td class="mono">tasks.md</td></tr>
-        <tr><td class="mono">check</td><td>Verify</td><td class="mono">四文档链</td><td>检查报告（通过/警告/失败）</td></tr>
+        <tr><td class="mono">check</td><td>Verify</td><td class="mono">四文档链 + working ontology</td><td>check_result + pending revision + 诊断</td></tr>
         <tr><td class="mono">apply</td><td>Apply</td><td class="mono">overview→proposal→spec/design/tasks</td><td>代码 + 测试 + checkbox 更新</td></tr>
         <tr><td class="mono">test</td><td>Test</td><td>代码 + test-strategy</td><td>测试证据（telemetry）</td></tr>
-        <tr><td class="mono">archive</td><td>Archive</td><td>变更全量</td><td class="mono">archive/ + report.md/.html + execution-log.md</td></tr>
+        <tr><td class="mono">archive</td><td>Archive</td><td>变更全量 + confirmed ontology</td><td class="mono">archive/&lt;date&gt;-&lt;name&gt;/ + reports/ + logs/ + 相邻 zip</td></tr>
       </tbody>
     </table>
+    <div class="callout reveal"><b>Full 与 Simple：</b><code>proposal.md</code> 始终在变更根目录；Full 把 spec/design/tasks 放在 <code>specs/&lt;capability&gt;/</code>，Simple 则放在变更根目录。归档目录重名时会安全使用 <code>-2</code>、<code>-3</code> 后缀。</div>
   </div>
 </section>
 
@@ -719,39 +898,44 @@ npx kld-sdd">复制</button>
 <section id="structure">
   <div class="wrap">
     <div class="sec-head reveal">
-      <span class="sec-num">§ 5</span>
+      <span class="sec-num">§ 6</span>
       <h2 class="sec-title">初始化后的目录结构</h2>
     </div>
-    <p class="sec-sub reveal">运行 <code>npx kld-sdd</code> 后，你的项目会长出这些目录。</p>
+    <p class="sec-sub reveal">运行 <code>npx kld-sdd</code> 后，会部署共享运行时与所选 Agent 的技能目录；下面只展开关键结构。</p>
 
     <div class="tree reveal"><span class="dir">your-project/</span>
 ├── <span class="dir">openspec/</span>
+│   ├── <span class="file">kld-sdd操作手册.html</span>       <span class="cmt"># 本指南的项目内副本</span>
 │   ├── <span class="dir">specs/</span>
-│   │   └── <span class="file">overview.md</span>          <span class="cmt"># 全局架构约束（数据字典、接口规范）</span>
-│   └── <span class="dir">changes/</span>                 <span class="cmt"># 变更工作区</span>
-│       └── <span class="dir">&lt;change-name&gt;/</span>          <span class="cmt"># propose/spec/design/tasks 落在此处</span>
-├── <span class="dir">openspec-templates/</span>          <span class="cmt"># 四文档参考模版（供参考）</span>
-│   ├── <span class="file">propose.md</span>
-│   ├── <span class="file">spec.md</span>
-│   ├── <span class="file">design.md</span>
-│   └── <span class="file">tasks.md</span>
-├── <span class="dir">.claude/</span>
-│   ├── <span class="dir">skills/opsx-*/</span>            <span class="cmt"># SDD skills（扁平一层，Claude 可识别）</span>
-│   ├── <span class="dir">hooks/sdd-*.cjs</span>          <span class="cmt"># Claude Code 门禁 hook（可选增强）</span>
-│   └── <span class="file">settings.json</span>            <span class="cmt"># hook 配置（含三层门禁绑定）</span>
-├── <span class="dir">.cursor/skills/opsx-*/</span>       <span class="cmt"># Cursor 技能</span>
-├── <span class="dir">.codebuddy/skills/opsx-*/</span>    <span class="cmt"># CodeBuddy 技能</span>
-├── <span class="dir">.kunlunzhima/</span>               <span class="cmt"># 昆仑智码</span>
-│   ├── <span class="dir">skills/opsx-*/</span>            <span class="cmt"># SDD skills（扁平一层）</span>
-│   └── <span class="dir">commands/opsx/</span>            <span class="cmt"># OPSX command bridge（轻量入口，指向对应 Skill）</span>
-├── <span class="dir">.agents/skills/opsx-*/</span>       <span class="cmt"># Codex 项目级技能</span>
-└── <span class="dir">skywalk-sdd/</span>                 <span class="cmt"># Telemetry 数据目录</span>
-    ├── <span class="file">log.cjs</span>                  <span class="cmt"># 本地 Telemetry CLI</span>
-    ├── <span class="dir">events/</span>                  <span class="cmt"># 事件数据（gitignored）</span>
-    ├── <span class="dir">state/</span>                   <span class="cmt"># 活跃阶段状态（gitignored）</span>
-    └── <span class="dir">git-hooks/ · ci/</span>         <span class="cmt"># 质量门禁 / CI 兜底模板</span></div>
-
-    <p class="lead reveal" style="margin-top:24px;font-size:.9rem">提示：Claude Code 只识别 <code>.claude/skills/&lt;skill-name&gt;/SKILL.md</code> 这一层；嵌套在 <code>skills/kld-sdd/opsx-*</code> 下不会被 <code>/</code> 菜单发现，所以 kld-sdd 部署时强制扁平化并清理旧版嵌套 bundle。昆仑智码用户可在 IDE 中使用 <code>.kunlunzhima/commands/opsx/</code> 下的 OPSX 命令入口。</p>
+│   │   └── <span class="file">overview.md</span>           <span class="cmt"># 全局架构约束</span>
+│   └── <span class="dir">changes/</span>
+│       ├── <span class="dir">&lt;change-name&gt;/</span>       <span class="cmt"># 活跃变更</span>
+│       │   ├── <span class="file">proposal.md</span>        <span class="cmt"># mode / change-id / change-type / test-strategy</span>
+│       │   ├── <span class="dir">specs/&lt;capability&gt;/</span> <span class="cmt"># Full：spec / design / tasks</span>
+│       │   ├── <span class="file">spec · design · tasks.md</span> <span class="cmt"># Simple：根目录三文档</span>
+│       │   ├── <span class="dir">ontology/</span>          <span class="cmt"># working-ontology · artifact-index · diagnostics · file-index · identities · continuity-resolution</span>
+│       │   ├── <span class="dir">artifacts/**/*.ontology.json</span>
+│       │   └── <span class="file">logs/execution-log.md</span>
+│       └── <span class="dir">archive/</span>
+│           ├── <span class="dir">&lt;date&gt;-&lt;name&gt;/</span>
+│           │   ├── <span class="dir">reports/</span>         <span class="cmt"># &lt;name&gt;-report.{md,html,json}</span>
+│           │   ├── <span class="dir">logs/</span>
+│           │   └── <span class="file">archive-ontology · canonical-facts · conversion-report · archive-manifest.json</span>
+│           └── <span class="file">&lt;date&gt;-&lt;name&gt;.zip</span> <span class="cmt"># 相邻 Archive Package</span>
+├── <span class="dir">openspec-templates/</span>           <span class="cmt"># proposal/spec/design/tasks/overview + continuity 示例</span>
+├── <span class="dir">.claude/</span>                     <span class="cmt"># skills + hooks + settings</span>
+├── <span class="dir">.cursor/skills/ · .qoder/skills/ · .workbuddy/skills/</span>
+├── <span class="dir">.codebuddy/</span>                  <span class="cmt"># skills + hooks + settings</span>
+├── <span class="dir">.kunlunzhima/</span>                <span class="cmt"># skills + commands/opsx bridge</span>
+├── <span class="dir">.opencode/skills/</span>            <span class="cmt"># skills-only，不部署 command bridge</span>
+├── <span class="dir">.agents/skills/</span>              <span class="cmt"># Codex 项目级技能</span>
+└── <span class="dir">skywalk-sdd/</span>
+    ├── <span class="file">log.cjs · metrics-v3.cjs · context-client.cjs</span>
+    ├── <span class="dir">ontology/</span> · <span class="file">apply-worktree-finish.cjs</span>
+    ├── <span class="dir">events/ · state/</span>           <span class="cmt"># 门禁信号源，gitignored</span>
+    └── <span class="dir">git-hooks/ · ci/</span>          <span class="cmt"># Git / CI 兜底模板</span></div>
+
+    <div class="callout reveal"><b>部署原则：</b>13 个可调用入口与 6 个 TDD 配套包会复制到每个已选择 Agent 的 skill 目录。只有 Claude Code 与 CodeBuddy 同时获得自动 Hook Pack；OpenCode 采用 skills-only，昆仑智码额外获得 13 个轻量 command bridge。</div>
   </div>
 </section>
 
@@ -759,22 +943,23 @@ npx kld-sdd">复制</button>
 <section id="editors">
   <div class="wrap">
     <div class="sec-head reveal">
-      <span class="sec-num">§ 6</span>
+      <span class="sec-num">§ 7</span>
       <h2 class="sec-title">支持的 AI 编辑器</h2>
     </div>
-    <p class="sec-sub reveal">8 个编辑器统一使用 <code>SKILL.md</code> 技能格式，初始化时自动创建目录。下方为各编辑器的简要上手方式。</p>
+    <p class="sec-sub reveal">8 个 Agent profile 统一使用 <code>SKILL.md</code>；只部署初始化时选中的 profile，并自动创建对应目录。</p>
 
     <table class="tbl reveal">
-      <thead><tr><th>编辑器</th><th>技能目录</th><th>技能支持</th><th>自动创建</th></tr></thead>
+      <caption>8 个 Agent 的技能入口、自动 Hook 与规则接线</caption>
+      <thead><tr><th scope="col">Agent</th><th scope="col">技能 / 入口</th><th scope="col">自动 Hook</th><th scope="col">规则接线</th></tr></thead>
       <tbody>
-        <tr><td>Cursor</td><td class="mono">.cursor/skills/</td><td class="yes">✅</td><td>已存在时</td></tr>
-        <tr><td>Claude Code</td><td class="mono">.claude/skills/</td><td class="yes">✅</td><td>已存在时</td></tr>
-        <tr><td>CodeBuddy</td><td class="mono">.codebuddy/skills/</td><td class="yes">✅</td><td class="yes">自动</td></tr>
-        <tr><td>Qoder</td><td class="mono">.qoder/skills/</td><td class="yes">✅</td><td class="yes">自动</td></tr>
-        <tr><td>OpenCode</td><td class="mono">.opencode/skills/</td><td class="yes">✅</td><td class="yes">自动</td></tr>
-        <tr><td>昆仑智码（KunlunZhima）</td><td class="mono">.kunlunzhima/skills/ + commands/opsx/</td><td class="yes">✅</td><td class="yes">自动</td></tr>
-        <tr><td>WorkBuddy</td><td class="mono">.workbuddy/skills/</td><td class="yes">✅</td><td class="yes">自动</td></tr>
-        <tr><td>Codex</td><td class="mono">.agents/skills/</td><td class="yes">✅</td><td class="yes">自动</td></tr>
+        <tr><td>Cursor</td><td class="mono">.cursor/skills/</td><td>—</td><td class="mono">.cursor/rules/*.mdc</td></tr>
+        <tr><td>Claude Code</td><td class="mono">.claude/skills/</td><td class="yes">L1 + L2</td><td class="mono">.claude/rules/*.md</td></tr>
+        <tr><td>CodeBuddy</td><td class="mono">.codebuddy/skills/</td><td class="yes">L1 + L2</td><td class="mono">.codebuddy/rules/*.md</td></tr>
+        <tr><td>Qoder</td><td class="mono">.qoder/skills/</td><td>—</td><td class="mono">.qoder/rules/*.md</td></tr>
+        <tr><td>OpenCode</td><td class="mono">.opencode/skills/（skills-only）</td><td>—</td><td class="mono">opencode.json instructions</td></tr>
+        <tr><td>昆仑智码</td><td class="mono">.kunlunzhima/skills/ + commands/opsx/</td><td>—</td><td class="mono">.kunlunzhima/.rules/*.mdc</td></tr>
+        <tr><td>WorkBuddy</td><td class="mono">.workbuddy/skills/</td><td>—</td><td class="mono">.workbuddy/rules/*.md + 上下文索引</td></tr>
+        <tr><td>Codex</td><td class="mono">.agents/skills/</td><td>—</td><td class="mono">AGENTS.md managed marker</td></tr>
       </tbody>
     </table>
 
@@ -788,7 +973,7 @@ npx kld-sdd">复制</button>
           <li>按工作流依次执行 spec → design → task → check → apply</li>
         </ol>
         <div class="cmd">/opsx-propose add-user-auth</div>
-        <p class="note">技能从 <code>.cursor/skills/opsx-*/</code> 自动加载；未部署自动 Hook，apply 前请确认已完成 check。</p>
+        <p class="note">技能从 <code>.cursor/skills/opsx-*/</code> 自动加载；规则由 <code>.cursor/rules/*.mdc</code> 原生加载。没有 L1/L2 Hook，apply 仍有通用 L3 自检与 Git/CI 证据门禁。</p>
       </div>
 
       <div class="editor-card reveal" id="ed-claude">
@@ -800,7 +985,7 @@ npx kld-sdd">复制</button>
           <li>按顺序走完 propose → spec → design → task → check → apply → archive</li>
         </ol>
         <div class="cmd">/opsx-propose add-user-auth</div>
-        <p class="note">已部署 <code>.claude/hooks/</code> 三层门禁（L1 Skill / L2 写入 / L3 自检），apply 前自动校验 check 状态。</p>
+        <p class="note">自动部署 <code>.claude/hooks/</code> 的 L1 Skill / L2 写入门禁，并保守合并 <code>settings.json</code>；L3 是所有 Agent 共用的 skill 自检。</p>
       </div>
 
       <div class="editor-card featured reveal" id="ed-codebuddy">
@@ -813,7 +998,7 @@ npx kld-sdd">复制</button>
           <li>SDD Hook Pack 已随初始化自动生效（lint / 测试 / 危险命令门禁），无需额外配置</li>
         </ol>
         <div class="cmd">/opsx-propose add-user-auth</div>
-        <p class="note">项目 Skills 在 <code>.codebuddy/skills/</code>，上下文文件为 <code>CODEBUDDY.md</code>。Windows 可用 <code>Alt+M</code> 切换权限模式；Hooks 比 Prompt 更可靠，适合 lint/test 门禁。</p>
+        <p class="note">项目 Skills 在 <code>.codebuddy/skills/</code>，上下文文件为 <code>CODEBUDDY.md</code>。初始化会自动部署 L1/L2 Hook Pack 并保守合并设置；L3 自检仍由 skill 执行。</p>
       </div>
 
       <div class="editor-card featured reveal" id="ed-kunlunzhima">
@@ -822,11 +1007,11 @@ npx kld-sdd">复制</button>
         <ol>
           <li>从企业平台安装 VSIX 插件，登录后打开项目</li>
           <li>切换到 <b>Craft</b> 模式（Win: <code>Alt+I</code>）进行多文件编码</li>
-          <li>在对话中输入 <code>/opsx-propose</code> 等 OPSX 命令，或从 <code>.kunlunzhima/commands/opsx/</code> 入口调用</li>
+          <li>在对话中输入 <code>/opsx:propose</code> 等 OPSX 命令，或从 <code>.kunlunzhima/commands/opsx/</code> 入口调用</li>
           <li>设置 → Skills 可查看/管理已加载的项目技能</li>
         </ol>
-        <div class="cmd">/opsx-propose add-user-auth</div>
-        <p class="note">项目 Skills 在 <code>.kunlunzhima/skills/</code>，命令 bridge 在 <code>.kunlunzhima/commands/opsx/</code>（指向对应 SKILL.md）。项目上下文文件为 <code>KunLunZhiMa.md</code>；IDE 无自动 Hook，质量靠 Skill 自检与 check 阶段保障。纯问答用 Ask 模式（<code>Alt+L</code>）。</p>
+        <div class="cmd">/opsx:propose add-user-auth</div>
+        <p class="note">项目 Skills 在 <code>.kunlunzhima/skills/</code>，13 个 command bridge 位于 <code>.kunlunzhima/commands/opsx/</code>。规则使用 <code>.kunlunzhima/.rules/*.mdc</code>；无自动 Hook，使用 L3 自检与 Git/CI 证据门禁。</p>
       </div>
 
       <div class="editor-card reveal" id="ed-qoder">
@@ -838,7 +1023,7 @@ npx kld-sdd">复制</button>
           <li>按工作流推进各阶段技能</li>
         </ol>
         <div class="cmd">/opsx-propose add-user-auth</div>
-        <p class="note">技能从 <code>.qoder/skills/opsx-*/</code> 加载；未部署自动 Hook。</p>
+        <p class="note">技能从 <code>.qoder/skills/opsx-*/</code> 加载，规则从 <code>.qoder/rules/*.md</code> 原生加载；未部署自动 Hook。</p>
       </div>
 
       <div class="editor-card reveal" id="ed-opencode">
@@ -851,7 +1036,7 @@ npx kld-sdd">复制</button>
           <li>按 propose → spec → design → task → check → apply 推进</li>
         </ol>
         <div class="cmd">/opsx-propose add-user-auth</div>
-        <p class="note">技能在 <code>.opencode/skills/opsx-*/</code>；OpenCode 将 skill 注册为 <code>/opsx-*</code> 斜杠命令。未部署 Hook。若同时 init Claude/Codex，OpenCode 也会读取 <code>.claude/skills</code> / <code>.agents/skills</code>，同名 skill 可能冲突；纯 OpenCode 可设 <code>OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=true</code>。</p>
+        <p class="note">技能在 <code>.opencode/skills/opsx-*/</code>，不部署独立 command bridge；规则接入 <code>opencode.json</code> 的 instructions。若同时 init Claude/Codex，OpenCode 也可能读取其 skill，同名冲突时可设 <code>OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=true</code>。</p>
       </div>
 
       <div class="editor-card reveal" id="ed-workbuddy">
@@ -863,7 +1048,7 @@ npx kld-sdd">复制</button>
           <li>按 propose → spec → design → task → check → apply 推进</li>
         </ol>
         <div class="cmd">/opsx-propose add-user-auth</div>
-        <p class="note">技能从 <code>.workbuddy/skills/opsx-*/</code> 加载。</p>
+        <p class="note">技能从 <code>.workbuddy/skills/opsx-*/</code> 加载；规则部署到 <code>.workbuddy/rules/*.md</code>，并使用上下文文件索引作兼容接线。</p>
       </div>
 
       <div class="editor-card reveal" id="ed-codex">
@@ -871,11 +1056,11 @@ npx kld-sdd">复制</button>
         <p>项目级 Agent，skills 部署在 <code>.agents/skills/</code> 供 Codex 会话引用。</p>
         <ol>
           <li>在项目根启动 Codex Agent 会话</li>
-          <li>输入 <code>/opsx-propose &lt;变更名&gt;</code> 或引用对应 Skill</li>
+          <li>输入 <code>$opsx-propose</code>、引用对应 Skill，或直接用自然语言说明要创建的变更</li>
           <li>按 SDD 工作流逐阶段执行</li>
         </ol>
-        <div class="cmd">/opsx-propose add-user-auth</div>
-        <p class="note">初始化会自动创建 <code>.agents/skills/opsx-*/</code>；未部署自动 Hook。</p>
+        <div class="cmd">$opsx-propose add-user-auth</div>
+        <p class="note">初始化会创建 <code>.agents/skills/opsx-*/</code>；<code>opsx-rules</code> 通过 AGENTS.md managed marker 接线。Codex 未部署 L1/L2 Hook，仍执行通用 L3 自检。</p>
       </div>
     </div>
   </div>
@@ -885,19 +1070,19 @@ npx kld-sdd">复制</button>
 <section id="team">
   <div class="wrap">
     <div class="sec-head reveal">
-      <span class="sec-num">§ 7</span>
+      <span class="sec-num">§ 8</span>
       <h2 class="sec-title">团队协作流程</h2>
     </div>
-    <p class="sec-sub reveal">一次初始化，全员复用。规范随 Git 提交，新成员 clone 即得一致环境。</p>
+    <p class="sec-sub reveal">规范、skills、归档报告与执行日志可随 Git 共享；本地 telemetry 状态和 Engineering KB 凭据保持隔离。</p>
 
     <div class="roles">
       <div class="role reveal">
         <h4>👤 架构师 / TL <span class="em">（配置一次）</span></h4>
         <ol>
           <li>在项目中运行 <code>npx kld-sdd</code></li>
-          <li>将团队规范文档放入 <code>team-configs/</code></li>
-          <li>将自定义 skills 放入 <code>.*/skills/</code></li>
-          <li>提交到 Git</li>
+          <li>运行 <code>opsx-rules generate</code> 生成 5 主题项目规则</li>
+          <li>使用 <code>opsx-rules review</code> 对照代码事实审查更新</li>
+          <li>提交规则、skills、OpenSpec 文档和归档产物</li>
         </ol>
       </div>
       <div class="role reveal">
@@ -905,11 +1090,12 @@ npx kld-sdd">复制</button>
         <ol>
           <li><code>git clone &lt;project&gt;</code></li>
           <li><code>npm install</code></li>
-          <li><code>npx kld-sdd</code> 一键配置所有 AI 工具</li>
-          <li>激活 <code>/opsx-propose</code> 开始工作</li>
+          <li><code>npx kld-sdd --tool &lt;agent&gt;</code> 部署本人使用的 profile</li>
+          <li>配置个人 Engineering KB API key，再激活 <code>opsx-propose</code></li>
         </ol>
       </div>
     </div>
+    <div class="callout reveal"><b>不会进 Git 的本地状态：</b><code>skywalk-sdd/events/</code>、<code>skywalk-sdd/state/</code> 与 KB 的 <code>.local/state.json</code>。新 clone 需要再次运行初始化以安装本地 Git hook；API key 不应写入仓库。</div>
   </div>
 </section>
 
@@ -917,43 +1103,62 @@ npx kld-sdd">复制</button>
 <section id="telemetry">
   <div class="wrap">
     <div class="sec-head reveal">
-      <span class="sec-num">§ 8</span>
-      <h2 class="sec-title">度量与三层门禁</h2>
+      <span class="sec-num">§ 9</span>
+      <h2 class="sec-title">度量、门禁与成熟度</h2>
+    </div>
+    <p class="sec-sub reveal">SkyWalk-SDD V3 以纯 CLI 采集结构化事件。单次变更报告只展示当前 change；项目级报告才负责跨变更聚合。</p>
+
+    <div class="metric-grid">
+      <div class="metric reveal"><div class="key">E1</div><h4>场景交付效率</h4><div class="value">有效阶段总时长 ÷ 场景数</div><p>包含返工阶段；没有可识别场景时标记不可用，不伪造分母。</p></div>
+      <div class="metric reveal"><div class="key">Q3</div><h4>规格质量分</h4><div class="value">(总项 − errors) ÷ 总项 × 100</div><p>warnings 与 suggestions 单独展示；独立 reviewer 才能得到 verified 状态。</p></div>
+      <div class="metric reveal"><div class="key">P4</div><h4>质量门禁执行率</h4><div class="value">首次 apply 前有 check = 1</div><p>用事件顺序验证流程纪律，而不是只看最终是否补过 check。</p></div>
+      <div class="metric reveal"><div class="key">P-R</div><h4>返工强度</h4><div class="value">次数 + 原因分布</div><p>记录需求、规格、设计、代码、测试等返工原因，支持趋势复盘。</p></div>
+      <div class="metric reveal"><div class="key">P-H</div><h4>Telemetry 健康度</h4><div class="value">doctor health × 100</div><p>与 P-C 阶段闭合率一起判断数据是否足够可信。</p></div>
     </div>
-    <p class="sec-sub reveal">SkyWalk-SDD 把度量嵌入 skill 流程自动采集，无需配置 MCP；apply 前置三层门禁确保变更已通过 check。</p>
 
-    <p class="lead reveal" style="margin-top:24px"><b>SkyWalk-SDD Telemetry</b>：事件落 <code>skywalk-sdd/events/</code>（gitignored），最终报告落 <code>openspec/changes/&lt;change&gt;/reports/</code>，执行日志随 change 提交。</p>
+    <p class="lead reveal" style="margin-top:32px"><b>事件与单变更报告</b>：事件落 <code>skywalk-sdd/events/</code>、活跃状态落 <code>skywalk-sdd/state/</code>（均 gitignored）；归档报告落 <code>openspec/changes/archive/&lt;date&gt;-&lt;name&gt;/reports/</code>。</p>
     <div class="codeblock reveal">
-      <button class="copy" data-copy="node skywalk-sdd/log.cjs start  --command=propose --project=. --change=xxx
-node skywalk-sdd/log.cjs end    --event-id=evt_xxx --result=success --summary=&quot;...&quot;
-node skywalk-sdd/log.cjs metrics --project=.">复制</button>
-<pre><span class="k-c"># 阶段开始 / 结束 / 查看四维度指标</span>
-<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">start</span>  --command=propose --project=. --change=xxx
-<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">end</span>    --event-id=evt_xxx --result=success --summary=<span class="k-o">"..."</span>
-<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">metrics</span> --project=.</pre>
+      <button type="button" class="copy" data-copy="node skywalk-sdd/log.cjs start --command=propose --project=. --change=add-user-auth --agent=codex --source=opsx-skill --session-id=sess_001
+node skywalk-sdd/log.cjs end --event-id=evt_xxx --project=. --result=success --summary=&quot;proposal 完成&quot;
+node skywalk-sdd/log.cjs report --project=. --change=add-user-auth --format=html --output=reports/add-user-auth.html">复制</button>
+<pre><span class="k-c"># skill 会自动调用；手工排障时也可直接运行</span>
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">start</span> --command=propose --project=. --change=add-user-auth --agent=codex --source=opsx-skill --session-id=sess_001
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">end</span> --event-id=evt_xxx --project=. --result=success --summary=<span class="k-o">"proposal 完成"</span>
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">report</span> --project=. --change=add-user-auth --format=html --output=reports/add-user-auth.html</pre>
     </div>
 
-    <p class="lead reveal" style="margin-top:32px"><b>apply 前三层门禁体系</b>：</p>
+    <p class="lead reveal" style="margin-top:32px"><b>双周 / 月度跟踪</b>：周期报告要求完整窗口，并自动构建当前、前一期、前两期的对比。</p>
+    <div class="codeblock reveal">
+      <button type="button" class="copy" data-copy="node skywalk-sdd/log.cjs report --project=. --period=biweekly --date-from=2026-07-15 --date-to=2026-07-28 --format=html --output=reports/biweekly-2026-07-28.html
+node skywalk-sdd/log.cjs report --project=. --period=monthly --date-from=2026-07-01 --date-to=2026-07-31 --format=html --output=reports/monthly-2026-07.html">复制</button>
+<pre><span class="k-c"># 双周必须是含首尾 14 天；月度必须是完整自然月</span>
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">report</span> --project=. --period=biweekly --date-from=2026-07-15 --date-to=2026-07-28 --format=html --output=reports/biweekly-2026-07-28.html
+<span class="k-p">➜</span> <span class="k-s">node</span> skywalk-sdd/log.cjs <span class="k-f">report</span> --project=. --period=monthly --date-from=2026-07-01 --date-to=2026-07-31 --format=html --output=reports/monthly-2026-07.html</pre>
+    </div>
+    <div class="callout reveal"><b>输出口径：</b>独立 <code>report</code> 一次输出所选格式（默认 HTML；未给 <code>--output</code> 时打印到终端）。<code>opsx-archive</code> 固定生成 <code>report.md + report.html + report.json</code> 三产物，并只登记真实写入成功的文件。单次变更 HTML 是桌面四页签：概览、指标与阶段、问题与证据、产物与追溯；标准测量阶段为 propose/spec/design/task/check/apply/archive，test/explore 只作辅助证据。文档完成度与事件可追溯度、问题类别数与规则命中次数、指标可计算性与可信度分别展示。P50/P75/P90 等趋势只属于项目级报告。</div>
+
+    <p class="lead reveal" style="margin-top:32px"><b>apply 前门禁体系</b>：</p>
     <div class="gates">
       <div class="gate reveal">
-        <div class="lv">L1 · SKILL 级</div>
+        <div class="lv">L1 · SKILL 级 · Claude / CodeBuddy</div>
         <h4>PreToolUse(Skill) 阻断</h4>
         <p>在 Skill 被调用的瞬间阻断：指定 change 精确检查是否完成 check；未指定则扫描所有变更，至少一个完成 check 才放行。</p>
         <div class="f">sdd-skill-apply-gate.cjs</div>
       </div>
       <div class="gate reveal">
-        <div class="lv">L2 · 文件写入</div>
+        <div class="lv">L2 · 文件写入 · Claude / CodeBuddy</div>
         <h4>PreToolUse(Write|Edit) 阻断</h4>
         <p>在文件写入操作时阻断，防止未通过 check 的变更直接落代码。与 L1 形成双重保障。</p>
         <div class="f">sdd-apply-gate.cjs</div>
       </div>
       <div class="gate reveal">
-        <div class="lv">L3 · SKILL 自检</div>
+        <div class="lv">L3 · SKILL 自检 · 全部 Agent</div>
         <h4>技能内部自检</h4>
         <p>opsx-apply SKILL.md Step 1.2 作为最后一道防线，主动确认 check 已完成，未完成强制拒绝。</p>
         <div class="f">opsx-apply/SKILL.md §1.2</div>
       </div>
     </div>
+    <div class="callout reveal"><b>不要混淆：</b>只有 Claude Code 与 CodeBuddy 自动获得 L1/L2 Hook；Cursor、Qoder、昆仑智码、OpenCode、WorkBuddy、Codex 依靠通用 L3 自检，再由 Git hook / CI 的证据门禁兜底。</div>
   </div>
 </section>
 
@@ -961,38 +1166,48 @@ node skywalk-sdd/log.cjs metrics --project=.">复制</button>
 <section id="faq">
   <div class="wrap">
     <div class="sec-head reveal">
-      <span class="sec-num">§ 9</span>
+      <span class="sec-num">§ 10</span>
       <h2 class="sec-title">常见问题</h2>
     </div>
     <div class="faq">
       <div class="faq-item reveal">
-        <button class="faq-q">openspec 是什么，必须安装吗？<span class="chev">+</span></button>
-        <div class="faq-a"><div class="inner"><p><code>openspec</code> 是管理 SDD 变更目录的 CLI 工具（负责创建变更目录和读取指导规则）。运行 <code>npx kld-sdd</code> 时会自动安装；若安装失败，手动创建 <code>openspec/changes/&lt;name&gt;/</code> 目录后 skills 仍然可用。</p></div></div>
+        <button type="button" class="faq-q" id="faq-q-1" aria-expanded="false" aria-controls="faq-a-1">OpenSpec 是什么，必须安装吗？<span class="chev" aria-hidden="true">+</span></button>
+        <div class="faq-a" id="faq-a-1" role="region" aria-labelledby="faq-q-1" aria-hidden="true"><div class="inner"><p><code>openspec</code> 负责变更列表、创建、状态与阶段指导。初始化会先检测，缺失时询问是否安装；拒绝或安装失败仍可继续部署 kld-sdd，但依赖 <code>openspec list/new/status/instructions</code> 的阶段会降级，不能只靠手建目录获得完整体验。</p></div></div>
+      </div>
+      <div class="faq-item reveal">
+        <button type="button" class="faq-q" id="faq-q-2" aria-expanded="false" aria-controls="faq-a-2">为什么是 13 + 6，而不是 19 个命令？<span class="chev" aria-hidden="true">+</span></button>
+        <div class="faq-a" id="faq-a-2" role="region" aria-labelledby="faq-q-2" aria-hidden="true"><div class="inner"><p>13 个是可直接调用的入口：8 个生命周期技能、3 个辅助技能，以及 <code>opsx-ontology-query</code> / <code>opsx-kb-ingest</code>。另外 6 个 <code>opsx-tdd-*</code> 是被主流程加载的配套能力包，不注册为独立命令；初始化总共部署 19 个 skill 目录。</p></div></div>
+      </div>
+      <div class="faq-item reveal">
+        <button type="button" class="faq-q" id="faq-q-3" aria-expanded="false" aria-controls="faq-a-3">我选择的 Agent 目录不存在怎么办？<span class="chev" aria-hidden="true">+</span></button>
+        <div class="faq-a" id="faq-a-3" role="region" aria-labelledby="faq-q-3" aria-hidden="true"><div class="inner"><p>运行 <code>npx kld-sdd --tool &lt;agent&gt;</code> 会自动创建所选 profile 的技能目录。未选择的 Agent 不会被部署；可用逗号一次选择多个，或使用 <code>--tool all</code>。</p></div></div>
       </div>
       <div class="faq-item reveal">
-        <button class="faq-q">我用 CodeBuddy 或 Codex，目录不存在怎么办？<span class="chev">+</span></button>
-        <div class="faq-a"><div class="inner"><p>不用担心，运行 <code>npx kld-sdd</code> 会自动创建 <code>.codebuddy/skills/</code>、<code>.kunlunzhima/</code>、<code>.agents/skills/</code> 等目录。只需在初始化时按提示选择对应编辑器即可。</p></div></div>
+        <button type="button" class="faq-q" id="faq-q-4" aria-expanded="false" aria-controls="faq-a-4">opsx-propose 和直接让 AI 写代码有什么区别？<span class="chev" aria-hidden="true">+</span></button>
+        <div class="faq-a" id="faq-a-4" role="region" aria-labelledby="faq-q-4" aria-hidden="true"><div class="inner"><p>propose 会先确认模式、测试策略、变更类型、change-id 与 Continuity，再由 spec/design/task 把意图变成可追踪契约。本体层同步物化实体与关系，apply 按已通过 check 的契约实施，显著减少隐含假设和返工。</p></div></div>
       </div>
       <div class="faq-item reveal">
-        <button class="faq-q">opsx-propose 和直接让 AI 写代码有什么区别？<span class="chev">+</span></button>
-        <div class="faq-a"><div class="inner"><p>直接让 AI 写代码，AI 会凭空假设很多细节，导致返工。SDD 流程强制先把"要做什么"写清楚——propose 问清意图、spec 写成精确契约、design 定方案、task 拆成原子任务，AI 按契约实现，减少歧义和返工。</p></div></div>
+        <button type="button" class="faq-q" id="faq-q-5" aria-expanded="false" aria-controls="faq-a-5">团队规范已经有了，怎么让每个 Agent 加载？<span class="chev" aria-hidden="true">+</span></button>
+        <div class="faq-a" id="faq-a-5" role="region" aria-labelledby="faq-q-5" aria-hidden="true"><div class="inner"><p>运行 <code>opsx-rules generate</code> 生成架构、编码、测试、数据安全、Git 提交五类规则，再用 <code>opsx-rules review</code> 审查更新。它会按 profile 写入原生规则目录或配置接线，而不是依赖已移除的 <code>team-configs/</code>。</p></div></div>
       </div>
       <div class="faq-item reveal">
-        <button class="faq-q">团队规范已经有了，怎么让 AI 每次都遵守？<span class="chev">+</span></button>
-        <div class="faq-a"><div class="inner"><p>将规范文档转为 skill 文件，部署到 <code>.*/skills/</code> 目录后，AI 编辑器激活该 skill 时会自动遵守这些规范。规范随 Git 提交，全员一致。</p></div></div>
+        <button type="button" class="faq-q" id="faq-q-6" aria-expanded="false" aria-controls="faq-a-6">check 阶段会修改我的文档吗？<span class="chev" aria-hidden="true">+</span></button>
+        <div class="faq-a" id="faq-a-6" role="region" aria-labelledby="faq-q-6" aria-hidden="true"><div class="inner"><p>不会修改人工编写的 proposal/spec/design/tasks 或业务代码。check 会完整重建可再生的 ontology、索引、diagnostics 与 telemetry，并把工作态 revision 标记为 pending；发现的问题仍交回对应 authoring skill 修正。</p></div></div>
       </div>
       <div class="faq-item reveal">
-        <button class="faq-q">check 阶段会修改我的文档吗？<span class="chev">+</span></button>
-        <div class="faq-a"><div class="inner"><p>不会。check 是<b>只读检查</b>，即使发现代码相关问题也只记录在检查报告中，不自动修复。文档修复由你决定，推荐运行对应的 <code>/opsx-spec</code> 或 <code>/opsx-design</code> 修复；代码修复在 <code>/opsx-apply</code> 阶段进行。</p></div></div>
+        <button type="button" class="faq-q" id="faq-q-7" aria-expanded="false" aria-controls="faq-a-7">报告和 Archive Package 在哪里？<span class="chev" aria-hidden="true">+</span></button>
+        <div class="faq-a" id="faq-a-7" role="region" aria-labelledby="faq-q-7" aria-hidden="true"><div class="inner"><p>归档目录是 <code>openspec/changes/archive/&lt;date&gt;-&lt;name&gt;/</code>，报告位于其 <code>reports/</code>，执行日志位于 <code>logs/</code>；完整 zip 与归档目录相邻。成功后 <code>opsx-kb-ingest</code> 会把 zip 入库，并可写入 <code>ingest-receipt.json</code>。</p></div></div>
       </div>
       <div class="faq-item reveal">
-        <button class="faq-q">apply 会自动帮我 git commit 吗？<span class="chev">+</span></button>
-        <div class="faq-a"><div class="inner"><p>不会。apply 遵循 <b>Git 只读策略</b>——禁止为度量自动 <code>git init/add/commit</code> 或创建分支；Git 仅作为可选度量数据源（只读 <code>git rev-parse HEAD</code> 等）。非 Git 项目用 <code>vcs_mode=no-git</code> 继续执行。只有用户明确要求时才允许提交。</p></div></div>
+        <button type="button" class="faq-q" id="faq-q-8" aria-expanded="false" aria-controls="faq-a-8">apply 会自动帮我 Git commit 吗？<span class="chev" aria-hidden="true">+</span></button>
+        <div class="faq-a" id="faq-a-8" role="region" aria-labelledby="faq-q-8" aria-hidden="true"><div class="inner"><p>Telemetry 不会为了度量偷偷执行 <code>git init/add/commit</code>。常规 apply 也不会擅自提交；只有用户明确授权 worktree 提交或合并流程时，才会按对应步骤执行 Git 写操作。非 Git 项目仍可用 <code>vcs_mode=no-git</code> 继续。</p></div></div>
       </div>
     </div>
   </div>
 </section>
 
+</main>
+
 <!-- footer -->
 <footer>
   <div class="wrap">
@@ -1001,10 +1216,12 @@ node skywalk-sdd/log.cjs metrics --project=.">复制</button>
     <div class="meta">
       <span>作者：郑浩天</span>
       <span class="sep">·</span>
-      <span>更新日期：2026-07-12</span>
+      <span>更新日期：2026-07-28</span>
     </div>
     <div class="links">
       <a href="https://www.npmjs.com/package/@hunterzheng/kld-sdd" target="_blank" rel="noopener">npm</a>
+      <a href="https://github.com/hunterzheng1/kld-sdd" target="_blank" rel="noopener">GitHub</a>
+      <a href="https://github.com/hunterzheng1/kld-sdd/issues" target="_blank" rel="noopener">Issues</a>
       <a href="#top">回到顶部 ↑</a>
     </div>
     <p style="margin-top:18px;opacity:.6">MIT License · 本页基于 kld-sdd 真实 README 与 SKILL.md 生成</p>
@@ -1046,8 +1263,11 @@ node skywalk-sdd/log.cjs metrics --project=.">复制</button>
         if (e.isIntersecting){
           var id = '#' + e.target.id;
           navLinks.forEach(function(a){
-            a.style.color = (a.getAttribute('href') === id) ? 'var(--accent)' : '';
-            a.style.background = (a.getAttribute('href') === id) ? 'var(--surface-2)' : '';
+            var active = a.getAttribute('href') === id;
+            a.style.color = active ? 'var(--accent)' : '';
+            a.style.background = active ? 'var(--surface-2)' : '';
+            if (active) a.setAttribute('aria-current', 'location');
+            else a.removeAttribute('aria-current');
           });
         }
       });
@@ -1058,10 +1278,20 @@ node skywalk-sdd/log.cjs metrics --project=.">复制</button>
   /* ── 移动端菜单 ── */
   var menuBtn = document.getElementById('menuBtn');
   var navLinksEl = document.getElementById('navLinks');
-  menuBtn && menuBtn.addEventListener('click', function(){ navLinksEl.classList.toggle('open'); });
+  function setMenu(open){
+    if (!menuBtn || !navLinksEl) return;
+    navLinksEl.classList.toggle('open', open);
+    menuBtn.setAttribute('aria-expanded', String(open));
+    menuBtn.setAttribute('aria-label', open ? '关闭页面导航' : '打开页面导航');
+  }
+  menuBtn && menuBtn.addEventListener('click', function(){
+    setMenu(!navLinksEl.classList.contains('open'));
+  });
   navLinksEl && navLinksEl.addEventListener('click', function(e){
-    if (e.target.tagName === 'A') navLinksEl.classList.remove('open');
+    if (e.target.tagName === 'A') setMenu(false);
   });
+  document.addEventListener('keydown', function(e){ if (e.key === 'Escape') setMenu(false); });
+  window.addEventListener('resize', function(){ if (window.innerWidth > 760) setMenu(false); });
 
   /* ── 管线阶段点击跳转 + 高亮 ── */
   document.querySelectorAll('.stage').forEach(function(stage){
@@ -1081,26 +1311,65 @@ node skywalk-sdd/log.cjs metrics --project=.">复制</button>
 
   /* ── FAQ 折叠 ── */
   document.querySelectorAll('.faq-q').forEach(function(btn){
+    var panel = document.getElementById(btn.getAttribute('aria-controls'));
+    btn.setAttribute('aria-expanded', 'false');
+    if (panel) panel.setAttribute('aria-hidden', 'true');
     btn.addEventListener('click', function(){
       var item = btn.parentElement;
       var wasOpen = item.classList.contains('open');
-      document.querySelectorAll('.faq-item').forEach(function(i){ i.classList.remove('open'); });
-      if (!wasOpen) item.classList.add('open');
+      document.querySelectorAll('.faq-item').forEach(function(i){
+        i.classList.remove('open');
+        var q = i.querySelector('.faq-q');
+        var a = i.querySelector('.faq-a');
+        if (q) q.setAttribute('aria-expanded', 'false');
+        if (a) {
+          a.setAttribute('aria-hidden', 'true');
+          a.style.maxHeight = '';
+        }
+      });
+      if (!wasOpen) {
+        item.classList.add('open');
+        btn.setAttribute('aria-expanded', 'true');
+        if (panel) {
+          panel.setAttribute('aria-hidden', 'false');
+          panel.style.maxHeight = panel.scrollHeight + 'px';
+        }
+      }
     });
   });
 
   /* ── 代码块复制 ── */
+  function copyText(text){
+    if (navigator.clipboard && window.isSecureContext) {
+      return navigator.clipboard.writeText(text).then(function(){ return true; }, function(){ return fallbackCopy(text); });
+    }
+    return Promise.resolve(fallbackCopy(text));
+  }
+  function fallbackCopy(text){
+    var input = document.createElement('textarea');
+    input.value = text;
+    input.setAttribute('readonly', '');
+    input.style.position = 'fixed';
+    input.style.opacity = '0';
+    document.body.appendChild(input);
+    input.select();
+    input.setSelectionRange(0, input.value.length);
+    var copied = false;
+    try { copied = document.execCommand('copy'); } catch (e) { copied = false; }
+    document.body.removeChild(input);
+    return copied;
+  }
   document.querySelectorAll('.copy').forEach(function(btn){
+    btn.setAttribute('aria-live', 'polite');
     btn.addEventListener('click', function(){
       var text = btn.getAttribute('data-copy') || '';
       /* 去掉行首 prompt 装饰，复制纯净命令 */
       var clean = text.replace(/➜\s*/g, '').replace(/#\s.*$/gm, '').trim();
-      if (navigator.clipboard) {
-        navigator.clipboard.writeText(clean).then(function(){
-          var orig = btn.textContent; btn.textContent = '已复制 ✓';
-          setTimeout(function(){ btn.textContent = orig; }, 1400);
-        });
-      }
+      var orig = btn.textContent;
+      copyText(clean).then(function(copied){
+        btn.textContent = copied ? '已复制 ✓' : '复制失败';
+        setTimeout(function(){ btn.textContent = orig; }, 1600);
+      });
     });
   });
 })();