@c4a/context 0.7.20 → 0.7.25

package/docs/guides/knowledge-updates.md

@@ -217,7 +217,7 @@ In the work-start report or current plan, briefly state the affected articles'
 intended placements and reused category intent. For proposed top-level additions,
 renames, removals or changes of purpose, show the before/after tree, why reuse is
 insufficient, affected existing pages and reading order. Present that change for
-human review before applying it. This uses the existing report feedback where
+human review under `context.gate.top_level_directory` before applying it. This uses the existing report feedback where
 available; do not add a new CLI state, schema field or routine per-article gate.
 Explicit user approval of that concrete structure is sufficient; do not ask again.
 General permission to write knowledge or organize batches is not approval to
@@ -587,6 +587,10 @@ before delivery; inspect both new content and the old articles' disposition.
 
 Preview approved-page retirement with `context task retire --input <file> --format json`:
 
+This standalone retirement does not enter the article HTML Review. Apply
+`context.gate.deletion_scope` to its target list; an already approved deletion
+needs no second confirmation after the preview.
+
 ```yaml
 reason: These reader tasks are now covered by the approved guide.
 targets:

package/docs/guides/workspace-prepare.md

@@ -1,5 +1,9 @@
 # Prepare a workspace for the next task
 
+Agent policy: `context.gate.workspace_reset_restore`. A clear request to
+prepare this workspace authorizes the described task-state cleanup; clarify
+only an unresolved target or loss.
+
 Use only for an explicit workspace preparation request. The goal is usable
 registered sources and no unfinished task, while retaining approved knowledge
 and configuration. Lead with Host tools and actual observations; do not start

package/docs/guides/workspace-restore.md

@@ -1,5 +1,8 @@
 # Restore a historical workspace version
 
+Agent policy: `context.gate.workspace_reset_restore`. An explicit restore
+request needs no second approval when the target and affected files are clear.
+
 Use the Agent's Git and environment tools. This restores selected workspace
 files and usable sources; it does not reset the entire repository, rewind source
 repositories, or restore ignored runtime progress.
@@ -19,7 +22,8 @@ Compare target files with current tracked, untracked and staged files. Include
 current additions absent at the target in the proposed removal scope. Keep
 unrelated files, existing staged work and ignored source checkouts. Account for
 workspace moves or renames instead of treating a missing old path as an empty
-version. Reuse explicit authorization; ask when the target or loss is unresolved.
+version. Reuse explicit authorization; clarify an unresolved target or loss
+before acting rather than asking for a second approval of the same request.
 
 ## Restore files and environment
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context",
-  "version": "0.7.20",
+  "version": "0.7.25",
   "type": "module",
   "description": "Declarative SDK for Context knowledge sources, workflows, review, and package outputs",
   "license": "MIT",

package/templates/package-templates/kb/skills/knowledge-query/SKILL.md

@@ -81,9 +81,10 @@ phrases, or several large indexes, run the bundled
 node <current knowledge-query Skill directory>/scripts/search.mjs --query '<terms>' --limit 8
 ```
 
-The script locates `{{packageName}}` when it runs inside the package tree. If a
-package manager copied this Skill elsewhere, add `--root <package directory
-containing context-build-inventory.json>`, or use `--base <package collection>`
+The script locates `{{packageName}}` when it runs inside the package tree. It accepts
+the build inventory at the package root or its distributed copy under
+`others/context/`. If a package manager copied this Skill elsewhere, add
+`--root <package directory>`, or use `--base <package collection>`
 to locate this package by its inventory name. It chunks Markdown mechanically
 by headings and bounded line ranges, then returns paths, line ranges, headings,
 and previews; it does not interpret meaning.
@@ -138,7 +139,8 @@ explicitly accept the unchanged default during Context package-template review.
 
 After answering from the pages actually read, optionally append one or more
 related document links in the final summary. Read `context-site-map.json` from
-the selected package (or its sibling website output in a workspace). Match the
+the selected package root, then `others/context/context-site-map.json`, or its
+sibling website output in a workspace. Match the
 read page to `pages[].package_path` or `approved_path`; use its `title` and resolve
 `site_path` relative to `site_url`. The URL already includes the deployment base
 path: do not prepend `base` again. Only cite matched articles, deduplicate links,

package/templates/package-templates/kb/skills/knowledge-query/scripts/search.mjs

@@ -51,7 +51,14 @@ function parseArgs(argv) {
 }
 
 function isPackageRoot(directory) {
-  return existsSync(join(directory, "context-build-inventory.json"));
+  return inventoryPath(directory) !== undefined;
+}
+
+function inventoryPath(directory) {
+  return [
+    join(directory, "context-build-inventory.json"),
+    join(directory, "others", "context", "context-build-inventory.json"),
+  ].find((path) => existsSync(path));
 }
 
 function ancestorPackageRoot(start) {
@@ -66,8 +73,8 @@ function ancestorPackageRoot(start) {
 
 function findInventories(directory, depth = 0) {
   if (!existsSync(directory) || depth > 5) return [];
-  const inventory = join(directory, "context-build-inventory.json");
-  if (existsSync(inventory)) return [inventory];
+  const inventory = inventoryPath(directory);
+  if (inventory !== undefined) return [inventory];
   const matches = [];
   for (const entry of readdirSync(directory, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
@@ -76,6 +83,12 @@ function findInventories(directory, depth = 0) {
   return matches;
 }
 
+function packageRootFromInventory(inventory) {
+  return inventory.endsWith(join("others", "context", "context-build-inventory.json"))
+    ? dirname(dirname(dirname(inventory)))
+    : dirname(inventory);
+}
+
 function inventoryPackageName(inventoryPath) {
   try {
     return JSON.parse(readFileSync(inventoryPath, "utf8"))?.package?.name;
@@ -99,7 +112,7 @@ function resolvePackageRoot(explicitRoot, packageCollection) {
   }
   const inventories = findInventories(resolve(packageCollection));
   const matching = inventories.filter((path) => inventoryPackageName(path) === PACKAGE_NAME);
-  if (matching.length === 1) return dirname(matching[0]);
+  if (matching.length === 1) return packageRootFromInventory(matching[0]);
   if (matching.length > 1) {
     throw new Error(`multiple installed packages named ${PACKAGE_NAME}; pass --root explicitly`);
   }
@@ -107,10 +120,10 @@ function resolvePackageRoot(explicitRoot, packageCollection) {
 }
 
 function knowledgeRoots(packageRoot) {
-  const inventoryPath = join(packageRoot, "context-build-inventory.json");
+  const packageInventoryPath = inventoryPath(packageRoot);
   let declared = [];
   try {
-    const inventory = JSON.parse(readFileSync(inventoryPath, "utf8"));
+    const inventory = JSON.parse(readFileSync(packageInventoryPath, "utf8"));
     declared = Object.values(inventory?.package?.distribution?.roots ?? {})
       .filter((value) => typeof value === "string");
   } catch {

package/templates/package-templates.zh-CN/kb/skills/knowledge-query/SKILL.md

@@ -60,7 +60,7 @@ description: 查询 {{displayName}} 中经过审核、可追溯来源的知识
 node <当前 knowledge-query Skill 目录>/scripts/search.mjs --query '<关键词>' --limit 8
 ```
 
-脚本位于知识包目录内时会自动定位 `{{packageName}}`。如果包管理工具将本 Skill 复制到了其他位置，增加 `--root <包含 context-build-inventory.json 的包目录>`；也可以使用 `--base <多包集合根目录>`，按构建清单中的包名定位。它按 Markdown 标题和固定行块机械切分，返回路径、行号、标题和短预览，不判断内容语义。
+脚本位于知识包目录内时会自动定位 `{{packageName}}`。它兼容包根的构建清单及 `others/context/` 下的分发副本。如果包管理工具将本 Skill 复制到了其他位置，增加 `--root <知识包目录>`；也可以使用 `--base <多包集合根目录>`，按构建清单中的包名定位。它按 Markdown 标题和固定行块机械切分，返回路径、行号、标题和短预览，不判断内容语义。
 
 搜索命中只是线索。回答前打开命中的页面和章节；关系或影响范围须引用实际说明该关系的正文，不能用 BM25 分数或文本共现代替。
 
@@ -101,7 +101,7 @@ node <当前 knowledge-query Skill 目录>/scripts/search.mjs --query '<关键
 ## 总结中的网站文档链接
 
 完成正文检索和回答后，仅在最终总结中按需附上一篇或多篇实际读取过的相关文档链接。
-从当前知识包读取 `context-site-map.json`，按命中文章的包内路径匹配
+依次从当前知识包根、`others/context/context-site-map.json` 或工作区网站输出读取站点映射，按命中文章的包内路径匹配
 `pages[].package_path`，使用 `title` 作链接文字，将 `site_path` 相对
 `site_url` 拼接。`site_url` 已包含站点子路径，不再重复拼接 `base`。
 同一文章只列一次，不凭标题推测页面地址或章节锚点。

package/templates/package-templates.zh-CN/kb/skills/knowledge-query/scripts/search.mjs

@@ -51,7 +51,14 @@ function parseArgs(argv) {
 }
 
 function isPackageRoot(directory) {
-  return existsSync(join(directory, "context-build-inventory.json"));
+  return inventoryPath(directory) !== undefined;
+}
+
+function inventoryPath(directory) {
+  return [
+    join(directory, "context-build-inventory.json"),
+    join(directory, "others", "context", "context-build-inventory.json"),
+  ].find((path) => existsSync(path));
 }
 
 function ancestorPackageRoot(start) {
@@ -66,8 +73,8 @@ function ancestorPackageRoot(start) {
 
 function findInventories(directory, depth = 0) {
   if (!existsSync(directory) || depth > 5) return [];
-  const inventory = join(directory, "context-build-inventory.json");
-  if (existsSync(inventory)) return [inventory];
+  const inventory = inventoryPath(directory);
+  if (inventory !== undefined) return [inventory];
   const matches = [];
   for (const entry of readdirSync(directory, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
@@ -76,6 +83,12 @@ function findInventories(directory, depth = 0) {
   return matches;
 }
 
+function packageRootFromInventory(inventory) {
+  return inventory.endsWith(join("others", "context", "context-build-inventory.json"))
+    ? dirname(dirname(dirname(inventory)))
+    : dirname(inventory);
+}
+
 function inventoryPackageName(inventoryPath) {
   try {
     return JSON.parse(readFileSync(inventoryPath, "utf8"))?.package?.name;
@@ -99,7 +112,7 @@ function resolvePackageRoot(explicitRoot, packageCollection) {
   }
   const inventories = findInventories(resolve(packageCollection));
   const matching = inventories.filter((path) => inventoryPackageName(path) === PACKAGE_NAME);
-  if (matching.length === 1) return dirname(matching[0]);
+  if (matching.length === 1) return packageRootFromInventory(matching[0]);
   if (matching.length > 1) {
     throw new Error(`multiple installed packages named ${PACKAGE_NAME}; pass --root explicitly`);
   }
@@ -107,10 +120,10 @@ function resolvePackageRoot(explicitRoot, packageCollection) {
 }
 
 function knowledgeRoots(packageRoot) {
-  const inventoryPath = join(packageRoot, "context-build-inventory.json");
+  const packageInventoryPath = inventoryPath(packageRoot);
   let declared = [];
   try {
-    const inventory = JSON.parse(readFileSync(inventoryPath, "utf8"));
+    const inventory = JSON.parse(readFileSync(packageInventoryPath, "utf8"));
     declared = Object.values(inventory?.package?.distribution?.roots ?? {})
       .filter((value) => typeof value === "string");
   } catch {