@chengzhao-dev/dsh-cpp-workflow 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chengzhao-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,107 @@
+# dsh-cpp-workflow
+
+[中文](README.md)
+
+Two skills for C++20 source work and build work. The plugin registers a skill provider only; it does not register tools, compile, download a toolchain, or write project files.
+
+## What it provides
+
+| Skill | Covers | Open it when |
+| --- | --- | --- |
+| `developing-cpp` | Behavior, boundaries, declarations, implementation; naming, exceptions, and source comments in `.h` / `.cpp` | The user names source code, or the work is a new project or whole-stage refactor |
+| `building-cpp` | Build setup, tool configuration, checks; CMake, Ninja, Clang config, build scripts, and environment combinations | The change touches build files, tool config, or the environment declaration, or the project is first connected to a build |
+
+Both skills read the project skill `cpp-workflow-project` first. Without it, the workspace gate never exposes these names.
+
+## Install
+
+Pinned npm install:
+
+```bash
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.1.0
+```
+
+The matching Git tag:
+
+```bash
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.1.0
+```
+
+The desktop app owns the `desktop` profile. If the command-line `add` is rejected, add the plugin in the app settings and use the same pinned npm version. A Git tag install uses the prebuilt `lib/` committed in the repository and runs no build on the target machine; the package has no install script that needs approval.
+
+## Workspace gate
+
+Both conditions must hold before either skill appears:
+
+1. Walking up from the current directory to the Git root, the path contains `.agents/skills/cpp-workflow-project/SKILL.md`.
+2. Inside the same Git repository that owns the marker, outside the skipped directories, there is a first-party `CMakeLists.txt`, or a `.c`, `.cc`, `.cpp`, `.cxx`, `.h`, `.hh`, `.hpp`, or `.hxx` source file.
+
+If either condition fails, the list is empty: without the project skill, CMake or `.cpp` files alone do not match; with the project skill but no first-party CMake or C++ source file in the repository, the result is also empty. A docs-only repository or one that only copied the template does not match. Scan limits, skipped directories, and the eight boundary cases are in [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-boundaries.md).
+
+The packaged skills use rank 550. A project `.agents/skills` skill uses rank 200 and overrides a plugin skill with the same name; do not copy `developing-cpp` or `building-cpp` into a project.
+
+## Project conventions
+
+Copy [templates/cpp-workflow-project](templates/cpp-workflow-project) into the target repository's `.agents/skills/` directory, keeping the `cpp-workflow-project` directory name. Add only files that do not exist; do not overwrite existing source, `CMakeLists.txt`, or `.clang-*` files. The project skill records only facts that cannot be inferred from the source:
+
+- project and component names, source root;
+- library/program boundary and public header location;
+- an entry command that runs from the repository root;
+- stage-table path and terminology additions.
+
+Keep one `environment.json` per repository. Its three axes are intentionally empty in the template and must be filled with the project's real combination after copying; while empty, the four source steps still work, but build setup stops. The stage table records observable behavior, not internal refactors.
+
+## Environment combinations
+
+| Axis | Values | Meaning |
+| --- | --- | --- |
+| `host` | `windows`, `linux`, `macos` | Where the editor and agent shell run |
+| `build_host` | `native`, `wsl` | `wsl` is valid only with `host=windows` |
+| `compiler` | `clang`, `gcc` | One compiler per configuration |
+
+The generator is always Ninja. Build directories are `build/clang/` and `build/gcc/`; they are never shared. Analysis tools are always `clang-format`, `clang-tidy`, and `clangd`; GCC mode does not switch to another analyzer.
+
+Run the declaration check first, then the live check on the build host. `<skill-dir>` is the installed `building-cpp` directory, not a directory in the target project:
+
+```bash
+node "<skill-dir>/scripts/checking-environment.mjs" --project .
+node "<skill-dir>/scripts/checking-environment.mjs" --project . --live
+```
+
+`windows + native` is a valid combination, but this version ships no PowerShell build script; `--live` reports the missing POSIX shell, not a missing compiler. The checker never installs, downloads, or edits PATH.
+
+## Package layout
+
+```text
+dsh-cpp-workflow/
+├── lib/                 # build output, shipped in the npm package
+├── skills/              # developing-cpp and building-cpp
+├── templates/           # empty project template to copy
+├── package.json
+├── package-lock.json    # repository only, used by npm ci
+├── LICENSE
+├── README.md
+├── README.en.md
+├── cordis.patch.yml     # one insert row
+├── locale/              # Chinese and English title/description
+└── icon.svg
+```
+
+Maintenance notes: flow and gate in [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-flow.md), directory and npm whitelist in [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md), version rules in [docs/versioning.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/versioning.md).
+
+## Local development
+
+Requires Node.js 22 or newer.
+
+```bash
+npm ci
+npm test           # build, structural check, gate/environment/schema tests
+npm run check      # same as npm test
+npm run pack:check # inspect the npm package contents
+```
+
+Source lives in `src/`; `npm run build` writes `lib/`. The structural check is `scripts/checking-skill-links.mjs`. Tests do not invoke a local compiler; the environment checks use fixed version strings.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# dsh-cpp-workflow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](README.en.md)
+
+把 C++20 的源码工作和构建工作收成两个技能。插件只注册技能 provider，不注册工具、不编译、不下载工具链、不写项目文件。
+
+## 提供什么
+
+| 技能 | 管什么 | 什么时候打开 |
+| --- | --- | --- |
+| `developing-cpp` | 定行为、定边界、定声明、定实现；`.h` / `.cpp` 的命名、异常和源码注释 | 用户点名源码，或需要新建/整段重构源码 |
+| `building-cpp` | 定构建、定工具配置、通过检查；CMake、Ninja、Clang 配置、构建脚本和环境组合 | 改动落在构建文件、工具配置或环境声明上，或第一次接构建 |
+
+两个技能都先读项目技能 `cpp-workflow-project`。没有项目技能时，门禁不会放出这两个名字。
+
+## 安装
+
+npm 安装钉死版本：
+
+```bash
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.1.0
+```
+
+同版本的 Git 标签：
+
+```bash
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.1.0
+```
+
+桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。
+
+## 工作区门禁
+
+一个会话里要同时满足两件事，技能才会出现：
+
+1. 从当前目录向上、停在 git 根，沿途有 `.agents/skills/cpp-workflow-project/SKILL.md`。
+2. 这份标记所在的 git 仓库里，跳过目录之外，有第一方 `CMakeLists.txt`，或有 `.c`、`.cc`、`.cpp`、`.cxx`、`.h`、`.hh`、`.hpp`、`.hxx` 源文件。
+
+缺一件就返回空列表：没有项目技能时，即使仓库里有 CMake 或 `.cpp` 也不命中；有项目技能、但仓库里没有第一方 CMake 或 C++ 源文件，同样不命中。纯文档仓库、只复制了模板的仓库也不命中。扫描上限、跳过目录和八类边界情形见 [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-boundaries.md)。
+
+插件技能 rank 550。项目自己的 `.agents/skills` 技能 rank 200，会以同名覆盖插件；不要在项目里复制 `developing-cpp` 或 `building-cpp`。
+
+## 项目级约定
+
+把 [templates/cpp-workflow-project](templates/cpp-workflow-project) 整个复制到目标仓库的 `.agents/skills/` 下，目录名保持 `cpp-workflow-project`；只补还不存在的文件，不覆盖已有的源码、`CMakeLists.txt` 或 `.clang-*`。项目技能只写本工程特有的事实：
+
+- 工程名、组件名和源码根；
+- 库与程序的边界、公共头位置；
+- 从仓库根能直接运行的入口命令；
+- 阶段表路径和术语增补。
+
+`environment.json` 一个仓库只有一份。模板里的三个轴故意留空，复制后必须填成工程的真实组合；留空时源码四步仍能做，但定构建会停。阶段表只写可观察行为，不写内部重构。
+
+## 环境组合
+
+| 轴 | 允许值 | 说明 |
+| --- | --- | --- |
+| `host` | `windows`、`linux`、`macos` | 编辑器和代理壳在哪 |
+| `build_host` | `native`、`wsl` | `wsl` 只在 `host=windows` 时合法 |
+| `compiler` | `clang`、`gcc` | 一次配置一个编译器 |
+
+生成器固定 Ninja，构建目录是 `build/clang/` 与 `build/gcc/`，不共用 `build/`。诊断工具固定 `clang-format`、`clang-tidy`、`clangd`；GCC 模式也不换成别的分析器。
+
+构建前先跑声明校验，再在构建宿主上跑活动校验。`<skill-dir>` 是插件安装后的 `building-cpp` 目录，不是目标工程里的目录：
+
+```bash
+node "<skill-dir>/scripts/checking-environment.mjs" --project .
+node "<skill-dir>/scripts/checking-environment.mjs" --project . --live
+```
+
+`windows + native` 是合法组合，但本版没有 PowerShell 构建脚本；`--live` 会明确报告缺 POSIX 壳，而不是缺编译器。环境脚本不安装、不下载、不改 PATH。
+
+## 包结构
+
+```text
+dsh-cpp-workflow/
+├── lib/                 # 构建产物，随 npm 包发布
+├── skills/              # developing-cpp 与 building-cpp
+├── templates/           # 复制到项目的空模板
+├── package.json
+├── package-lock.json    # 只在仓库，供 npm ci
+├── LICENSE
+├── README.md
+├── README.en.md
+├── cordis.patch.yml     # 只 insert 一行
+├── locale/              # 中英文标题与描述
+└── icon.svg
+```
+
+边界与门禁的维护说明在 [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-flow.md)，目录和进包白名单在 [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md)，版本规则在 [docs/versioning.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/versioning.md)。
+
+## 本地开发
+
+需要 Node.js 22 或更新版本。
+
+```bash
+npm ci
+npm test           # 构建、结构检查、门禁/环境/schema 测试
+npm run check      # 同 npm test
+npm run pack:check # 核对 npm 包内容
+```
+
+源码在 `src/`，`npm run build` 生成 `lib/`。结构检查在 `scripts/checking-skill-links.mjs`；测试不调用本机编译器，环境检查用固定版本字符串。
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# dsh-cpp-workflow bundle patch.
+#
+# Additive only: insert one host row. No official row is edited, disabled or
+# replaced. The row loads this package's `main` entry, which registers the
+# packaged developing-cpp and building-cpp skills through `ctx.skills`.
+#
+# Install from npm or from the matching Git tag, for example:
+#
+#   dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.1.0
+#   dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.1.0
+#
+- insert:
+    - id: cpp-workflow
+      name: "@chengzhao-dev/dsh-cpp-workflow"

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="C++ workflow">
+  <rect width="64" height="64" rx="14" fill="#0d1117"/>
+  <path d="M24 14 10 32l14 18" fill="none" stroke="#58a6ff" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M40 14l14 18-14 18" fill="none" stroke="#58a6ff" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M27 24l5 8-5 8M37 24l-5 8 5 8" fill="none" stroke="#f0f6fc" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M14 56h36" stroke="#3fb950" stroke-width="4" stroke-linecap="round"/>
+</svg>

package/lib/index.js

@@ -0,0 +1,203 @@
+// dsh-cpp-workflow bundle entry.
+//
+// Registers the two packaged skills as one bundle-scoped skill provider. The
+// provider is read-only and scans only `skills/<name>/SKILL.md`; each skill
+// directory becomes the resourceBase so relative steps, references, examples
+// and assets resolve from the installed package.
+//
+// The provider scopes itself to real C++ workflow workspaces: `list()` returns
+// nothing unless the session cwd sits inside a git checkout that carries the
+// explicit `.agents/skills/cpp-workflow-project/SKILL.md` marker on the path to
+// the git root AND that checkout has first-party C++ or CMake evidence. A
+// Markdown-only repository, a docs folder, a project template, or a C++ sample
+// outside the checkout never sees these names. Source evidence is repository-
+// wide once the marker opts the checkout in; only the marker lookup ignores
+// sibling directories.
+//
+// Rank 550 is lower priority than project/user skills (project `.agents/skills`
+// 200, user `.agents/skills` 500) and higher priority than the bundled root
+// (600), so a project can override either skill by name without editing the
+// package. The project skill itself (cpp-workflow-project, rank 200) is a
+// separate name and does not collide.
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isCppWorkflowWorkspace } from './workspace.js';
+export const name = 'dsh-cpp-workflow';
+export const inject = ['skills'];
+const PROVIDER = 'dsh-cpp-workflow';
+const RANK = 550;
+const KNOWN_SKILLS = new Set(['building-cpp', 'developing-cpp']);
+const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const SKILLS_ROOT = path.join(PACKAGE_ROOT, 'skills');
+/** Minimal YAML frontmatter reader for the keys SKILL.md actually uses. */
+function parseFrontmatter(source) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(source);
+    if (!match)
+        return { data: {}, body: source };
+    const data = {};
+    const stack = [
+        { indent: -1, target: data },
+    ];
+    for (const rawLine of match[1].split(/\r?\n/)) {
+        const line = rawLine.replace(/\t/g, '  ');
+        if (!line.trim() || line.trimStart().startsWith('#'))
+            continue;
+        const indent = line.length - line.trimStart().length;
+        const pair = /^([A-Za-z0-9_.-]+):(?:\s*(.*))?$/.exec(line.trim());
+        if (!pair)
+            continue;
+        while (stack.length > 1 && indent <= stack[stack.length - 1].indent)
+            stack.pop();
+        const parent = stack[stack.length - 1].target;
+        const key = pair[1];
+        const value = (pair[2] ?? '').trim();
+        if (value === '') {
+            const child = {};
+            parent[key] = child;
+            stack.push({ indent, target: child });
+            continue;
+        }
+        parent[key] = parseScalar(value);
+    }
+    return { data, body: source.slice(match[0].length) };
+}
+function parseScalar(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        const quote = value[0];
+        const inner = value.slice(1, -1);
+        return quote === '"'
+            ? inner.replace(/\\"/g, '"').replace(/\\n/g, '\n')
+            : inner.replace(/''/g, "'");
+    }
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (value === 'null' || value === '~')
+        return null;
+    if (/^\[.*\]$/.test(value)) {
+        return value
+            .slice(1, -1)
+            .split(',')
+            .map((item) => parseScalar(item.trim()))
+            .filter((item) => item !== '');
+    }
+    return value;
+}
+async function readCandidate(skillDir) {
+    const skillFile = path.join(skillDir, 'SKILL.md');
+    let source;
+    try {
+        source = await readFile(skillFile, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const { data } = parseFrontmatter(source);
+    if (typeof data.name !== 'string' || !SKILL_NAME_RE.test(data.name))
+        return undefined;
+    if (!KNOWN_SKILLS.has(data.name))
+        return undefined;
+    if (typeof data.description !== 'string' || data.description.trim() === '')
+        return undefined;
+    if (data.name !== path.basename(skillDir))
+        return undefined;
+    const candidate = {
+        name: data.name,
+        description: data.description.trim(),
+        invocation: { modelInvocable: true, userInvocable: true },
+        source: 'bundled',
+        provider: PROVIDER,
+        rank: RANK,
+        locator: skillDir,
+        resourceBase: { kind: 'directory', path: skillDir },
+        path: skillFile,
+    };
+    if (typeof data.whenToUse === 'string' && data.whenToUse.trim()) {
+        candidate.whenToUse = data.whenToUse.trim();
+    }
+    if (data.metadata && typeof data.metadata === 'object' && !Array.isArray(data.metadata)) {
+        candidate.metadata = data.metadata;
+    }
+    return candidate;
+}
+async function listSkills(options = {}) {
+    if (options.signal?.aborted)
+        return [];
+    if (!(await isCppWorkflowWorkspace(options.cwd)))
+        return [];
+    if (options.signal?.aborted)
+        return [];
+    let entries;
+    try {
+        entries = await readdir(SKILLS_ROOT, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !KNOWN_SKILLS.has(entry.name))
+            continue;
+        if (options.signal?.aborted)
+            return [];
+        const candidate = await readCandidate(path.join(SKILLS_ROOT, entry.name));
+        if (candidate)
+            candidates.push(candidate);
+    }
+    candidates.sort((a, b) => a.name.localeCompare(b.name));
+    return candidates;
+}
+async function getSkill(candidate, options = {}) {
+    if (options.signal?.aborted)
+        return undefined;
+    if (!candidate || candidate.provider !== PROVIDER)
+        return undefined;
+    // A candidate can outlive a directory change in the same session. Re-check
+    // only when the caller supplies a cwd; a plain `get()` keeps working for
+    // candidates that were already discovered in this workspace.
+    if (options.cwd !== undefined && !(await isCppWorkflowWorkspace(options.cwd)))
+        return undefined;
+    if (!KNOWN_SKILLS.has(candidate.name))
+        return undefined;
+    const skillDir = candidate.locator;
+    if (typeof skillDir !== 'string')
+        return undefined;
+    const resolved = path.resolve(skillDir);
+    if (resolved !== SKILLS_ROOT && !resolved.startsWith(SKILLS_ROOT + path.sep))
+        return undefined;
+    if (path.basename(resolved) !== candidate.name)
+        return undefined;
+    let source;
+    try {
+        source = await readFile(path.join(resolved, 'SKILL.md'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const { data, body } = parseFrontmatter(source);
+    if (data.name !== candidate.name)
+        return undefined;
+    return {
+        name: candidate.name,
+        description: candidate.description,
+        ...(candidate.whenToUse ? { whenToUse: candidate.whenToUse } : {}),
+        invocation: candidate.invocation,
+        source: candidate.source,
+        provider: PROVIDER,
+        resourceBase: { kind: 'directory', path: resolved },
+        path: path.join(resolved, 'SKILL.md'),
+        ...(candidate.metadata ? { metadata: candidate.metadata } : {}),
+        content: body.trim(),
+    };
+}
+export function apply(ctx) {
+    ctx.skills.registerProvider(() => ({
+        name: PROVIDER,
+        list: listSkills,
+        get: getSkill,
+    }));
+}

package/lib/workspace.js

@@ -0,0 +1,168 @@
+// Workspace evidence for dsh-cpp-workflow.
+//
+// A repository opts in only when it carries the project skill on the path from
+// the session cwd up to the git root AND that repository carries first-party C++
+// or CMake evidence. A stray `CMakeLists.txt`, a sample under `templates/`, or a
+// CMake file above the git root is never enough. The git root is the
+// repository boundary: once the marker opts the repository in, evidence is
+// searched across the repository, not outside it or in a sibling checkout.
+import { access, readdir } from 'node:fs/promises';
+import path from 'node:path';
+export const PROJECT_SKILL = path.join('.agents', 'skills', 'cpp-workflow-project', 'SKILL.md');
+export const MAX_ASCENT = 64;
+export const MAX_SCAN_DEPTH = 12;
+export const MAX_SCAN_ENTRIES = 4000;
+const SKIPPED_DIRS = new Set([
+    '.git',
+    'node_modules',
+    'vendor',
+    'third_party',
+    'templates',
+    'build',
+    'temp',
+    '.cache',
+]);
+export const CPP_SOURCE_EXTENSIONS = new Set([
+    '.c',
+    '.cc',
+    '.cpp',
+    '.cxx',
+    '.h',
+    '.hh',
+    '.hpp',
+    '.hxx',
+]);
+export const CPP_BUILD_FILES = new Set(['CMakeLists.txt']);
+async function exists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Nearest enclosing git checkout, including a worktree's `.git` file. */
+export async function findGitRoot(cwd) {
+    if (typeof cwd !== 'string' || cwd.trim() === '')
+        return undefined;
+    let cursor;
+    try {
+        cursor = path.resolve(cwd);
+    }
+    catch {
+        return undefined;
+    }
+    for (let depth = 0; depth < MAX_ASCENT; depth += 1) {
+        if (await exists(path.join(cursor, '.git')))
+            return cursor;
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return undefined;
+        cursor = parent;
+    }
+    return undefined;
+}
+/**
+ * Find the nearest project-skill marker between `cwd` and the git root,
+ * inclusive. A marker above the git root never counts. The marker's directory
+ * is also returned for diagnostics, but evidence is repository-wide.
+ */
+export async function findProjectSkill(cwd, gitRoot) {
+    if (typeof cwd !== 'string' || cwd.trim() === '')
+        return undefined;
+    let cursor;
+    try {
+        cursor = path.resolve(cwd);
+    }
+    catch {
+        return undefined;
+    }
+    if (!gitRoot) {
+        gitRoot = await findGitRoot(cursor);
+        if (!gitRoot)
+            return undefined;
+    }
+    else {
+        gitRoot = path.resolve(gitRoot);
+        const relative = path.relative(gitRoot, cursor);
+        if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            return undefined;
+        }
+    }
+    for (let depth = 0; depth < MAX_ASCENT; depth += 1) {
+        const file = path.join(cursor, PROJECT_SKILL);
+        if (await exists(file))
+            return { file, root: cursor };
+        if (cursor === gitRoot)
+            return undefined;
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return undefined;
+        cursor = parent;
+    }
+    return undefined;
+}
+/** Boolean form of {@link findProjectSkill}. */
+export async function hasProjectSkill(cwd, gitRoot) {
+    return (await findProjectSkill(cwd, gitRoot)) !== undefined;
+}
+/**
+ * True when `root` contains at least one first-party `CMakeLists.txt` or C++
+ * source/header. Generated, dependency, template and build trees are skipped.
+ * The scan is bounded to 12 levels and 4000 directory entries.
+ */
+export async function hasCppProject(root) {
+    let seen = 0;
+    const queue = [{ dir: root, depth: 0 }];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current)
+            break;
+        let entries;
+        try {
+            entries = await readdir(current.dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            seen += 1;
+            if (seen > MAX_SCAN_ENTRIES)
+                return false;
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (current.depth >= MAX_SCAN_DEPTH)
+                    continue;
+                if (SKIPPED_DIRS.has(entry.name))
+                    continue;
+                queue.push({ dir: path.join(current.dir, entry.name), depth: current.depth + 1 });
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (CPP_BUILD_FILES.has(entry.name))
+                return true;
+            if (CPP_SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Session gate. Both halves are required:
+ *   1. the project skill sits between `cwd` and the git root (inclusive), and
+ *   2. that git repository contains first-party C++ or CMake evidence.
+ * No cwd, no git checkout, a marker above the git root, a marker only in a
+ * sibling directory, or a documentation-only repository returns false.
+ */
+export async function isCppWorkflowWorkspace(cwd) {
+    const gitRoot = await findGitRoot(cwd);
+    if (!gitRoot)
+        return false;
+    const project = await findProjectSkill(cwd, gitRoot);
+    if (!project)
+        return false;
+    return hasCppProject(gitRoot);
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "C++ Workflow",
+    "description": "Four source steps and three build steps for C++20 projects, checked against the environment the project declares."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "C++ 工程流程",
+    "description": "用源码四步与构建三步推进 C++20 工程，并在项目声明的环境组合里核对构建与 clang 工具链。"
+  }
+}