skill-family-engineering-kit 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.7.0 locale=en baseline=sha256:ed1c59e7cee6e7280d2569e554b07d3b3513f4f3318bf30e374e2d480320f2b7 -->
+## [0.7.0] - 2026-08-21
+
+This release exports the public canonical projection closure builder buildProjectionClosure (FG-4), so callers construct compileProjectionPlan-ready plan closures through one public entry instead of re-implementing the Kit-private ordering, serialization, and digest algorithms.
+
+### Added
+
+- Adds the public skill-family-engineering-kit/profile-spi subpath. It projects the three Profile SPI JSON resources together with the Contracts canonical profile-descriptor.schema.json, and exports schema loaders, verifyProfile, adoption-pin verification, and tightening-only override checks. The data-only verifier fails closed on missing pins and symlink/path escapes and never executes Profile entrypoints.
+- Adds buildProjectionClosure - a pure public builder accepting an array of {path, sha256, mode} members (an explicit type file is also accepted) and returning the canonical plan closure {digestAlgorithm sha256, digest, resourceCount, resources} that compileProjectionPlan accepts verbatim as previousOwnedClosure or externalCandidateClosure; an empty array yields the legal empty closure.
+- The builder shares one normalization and digest source of truth with the compiler closure re-verification - deterministic path.localeCompare ordering, duplicate-path and portable-collision refusal, and the sha256(JSON.stringify(normalizedResources)) byte contract; every refusal fails closed in the existing projection plan input invalid domain (SFC2004 invalid-manifest).
+
+### Changed
+
+- Keeps the compileProjectionPlan input contract unchanged and the four top-level commands (scaffold, adopt-plan, projection, check) unchanged; every 0.6.0 input still compiles to byte-identical plans. The package version moves in lockstep with the Foundation line while the contracts machine contract stays at 1.6.0.
+
+### Upgrade Notes
+
+Version 0.7.0 is the projection closure builder line. Callers that previously assembled plan closures locally must import buildProjectionClosure and pin exactly 0.7.0. A plan closure ({path, type, sha256, mode} members) is not the harness computeResourceClosure resource closure ({path, role, exists, sha256} members) - the two shapes and purposes differ and are not interchangeable.
+<!-- release-skill:changelog:end version=0.7.0 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.6.0 locale=en baseline=sha256:e84a44b51d513c123ce3c5e91c9e50374c6e899aa021adabe8e44c3ad86eb2b2 -->
 ## [0.6.0] - 2026-08-21
 

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,26 @@
 # 变更日志
 
+<!-- release-skill:changelog:start version=0.7.0 locale=zh-CN baseline=sha256:e6070267ab3db289caf998c4539055c3d39dfa16fb5bc7db44689b305fde2e81 -->
+## [0.7.0] - 2026-08-21
+
+本版导出公共规范投影闭包 builder buildProjectionClosure（FG-4），调用方经一个公共入口即可构造 compileProjectionPlan 可直接接受的计划闭包，不再复刻 Kit 私有的排序、序列化与摘要算法。
+
+### 新增
+
+- 新增公共 skill-family-engineering-kit/profile-spi 子路径。它投影三个 Profile SPI JSON 资源与 Contracts canonical profile-descriptor.schema.json，导出 Schema 加载器、verifyProfile、采用 pin 校验和只收紧 overrides 检查。纯数据校验器遇到 pin 缺失、符号链接或路径越界时失败关闭，绝不执行 Profile entrypoint。
+- 新增 buildProjectionClosure：纯函数公共 builder，接受 {path, sha256, mode} 成员数组（可接受显式 type file），返回规范计划闭包 {digestAlgorithm sha256, digest, resourceCount, resources}，可原样作为 compileProjectionPlan 的 previousOwnedClosure 或 externalCandidateClosure；空数组返回合法的空闭包。
+- builder 与编译器闭包复验共享同一规范化与摘要事实源：确定性 path.localeCompare 排序、重复路径与便携路径冲突拒绝、sha256(JSON.stringify(normalizedResources)) 字节合同；全部拒绝在既有 projection plan input invalid 领域内失败关闭（SFC2004 invalid-manifest）。
+
+### 变更
+
+- compileProjectionPlan 入参合同不变，四个顶层命令（scaffold、adopt-plan、projection、check）不变；全部 0.6.0 既有输入仍编译为字节不变的计划。包版本随 Foundation 线锁步，Contracts 机器合同保持 1.6.0。
+
+### 升级说明
+
+0.7.0 是投影闭包 builder 线。此前在本地组装计划闭包的调用方必须导入 buildProjectionClosure 并精确锁定 0.7.0。计划闭包（成员 {path, type, sha256, mode}）不是 harness computeResourceClosure 的资源闭包（成员 {path, role, exists, sha256}）——两者形状与用途不同，不能互换。
+<!-- release-skill:changelog:end version=0.7.0 locale=zh-CN -->
+
+
 <!-- release-skill:changelog:start version=0.6.0 locale=zh-CN baseline=sha256:e48a11bcbdffb317068cb751f914809360aa8f2e2b852b1e436696601f6a2a47 -->
 ## [0.6.0] - 2026-08-21
 

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,131 @@
+# 贡献者公约（Contributor Covenant Code of Conduct）
+
+本行为准则采用 Contributor Covenant 2.1 标准文本，来源明确：
+`https://www.contributor-covenant.org/version/2/1/code_of_conduct/`。
+译文与解读以英文原文为准；执行联系方式见文末。
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement through the
+source repository's private channels (see SECURITY.md for private reporting).
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+`https://www.contributor-covenant.org/version/2/1/code_of_conduct/`.
+
+Community Impact Guidelines were inspired by Mozilla's code of conduct
+enforcement ladder.
+
+For answers to common questions about this code of conduct, see the FAQ at
+`https://www.contributor-covenant.org/faq`.
+
+[homepage]: https://www.contributor-covenant.org

package/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# 贡献指南（skill-family-engineering-kit）
+
+本仓是 `skill-family-engineering-kit` 的公开发布镜像，只承载版本化发布物。开发在私有工作区进行，不在本仓公开。
+
+## 问题报告
+
+Bug 报告请在本仓 GitHub Issues 提交：https://github.com/ifoohoo/skill-family-engineering-kit/issues
+
+提交时请尽量提供：受影响版本、最小复现步骤、预期与实际行为。
+
+## 代码贡献
+
+未经事先讨论的 Pull Request 不予接受。请先通过 Issue 讨论变更的动机与范围，获得维护者确认后再提交 PR。
+
+## 行为准则
+
+互动请遵守本仓 CODE_OF_CONDUCT.md。
+
+## 安全报告
+
+漏洞报告渠道见本仓 SECURITY.md。请走 Private vulnerability reporting，不要以公开 Issue 提交漏洞。
+
+## 许可证
+
+贡献内容默认按 Apache-2.0 授权，与本包许可证一致。

package/README.md

@@ -4,29 +4,28 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.6.0 -->
+<!-- release-skill:release-version: 0.7.0 -->
 
 An engineering toolkit used in development and CI. There are **exactly four** top-level commands, and no fifth:
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.6.0** (2026-08-21)
+**0.7.0** (2026-08-21)
 
-This release extends the check command with the entry contract gate and the controlled relock transaction sub-actions, adds external frozen authority projection bindings (FG-3), and carries the nine-class check diagnostics (audit remediation C2).
+This release exports the public canonical projection closure builder buildProjectionClosure (FG-4), so callers construct compileProjectionPlan-ready plan closures through one public entry instead of re-implementing the Kit-private ordering, serialization, and digest algorithms.
 
 **Added**
 
-- Adds the check entries sub-action - runEntryContractCheck and checkEntriesAction run the shared entry contract gate (SFA-ENTRY-003/004/005/007 and SFA-CONTEXT-001/002) over skill-family.entry-contract.json and SKILL.md bytes; diagnosis only, zero writes.
-- Adds the check relock sub-action - runRelock and relockAction are the one controlled exception to the no-write rule - a fail-closed transaction writing exactly the two contained state documents (.foundation/file-registry.json and skill-family.managed-file-lock.json), with drift validation before the first write and zero writes on any refusal.
-- Adds external frozen authority projection bindings (FG-3) - PROJECTION_AUTHORITY_BINDING_KINDS freezes external-root and caller-bytes; external-root re-reads each authority source from a separate frozen directory through the strict no-follow reader, and caller-bytes binds caller-provided base64 authority bytes to declared sha256 digests with no authority filesystem access at all, keeping the target root free of forged local authority facts.
+- Adds the public skill-family-engineering-kit/profile-spi subpath. It projects the three Profile SPI JSON resources together with the Contracts canonical profile-descriptor.schema.json, and exports schema loaders, verifyProfile, adoption-pin verification, and tightening-only override checks. The data-only verifier fails closed on missing pins and symlink/path escapes and never executes Profile entrypoints.
+- Adds buildProjectionClosure - a pure public builder accepting an array of {path, sha256, mode} members (an explicit type file is also accepted) and returning the canonical plan closure {digestAlgorithm sha256, digest, resourceCount, resources} that compileProjectionPlan accepts verbatim as previousOwnedClosure or externalCandidateClosure; an empty array yields the legal empty closure.
+- The builder shares one normalization and digest source of truth with the compiler closure re-verification - deterministic path.localeCompare ordering, duplicate-path and portable-collision refusal, and the sha256(JSON.stringify(normalizedResources)) byte contract; every refusal fails closed in the existing projection plan input invalid domain (SFC2004 invalid-manifest).
 
 **Changed**
 
-- Extends check diagnostics to nine classes (adds version single-source consistency, public boundary validation, and platform subset declaration validation); COMMAND_SIDE_EFFECTS now documents the entries and relock sub-action semantics.
-- Keeps the four top-level commands (scaffold, adopt-plan, projection, check) unchanged; entries and relock are check sub-actions, not new commands.
+- Keeps the compileProjectionPlan input contract unchanged and the four top-level commands (scaffold, adopt-plan, projection, check) unchanged; every 0.6.0 input still compiles to byte-identical plans. The package version moves in lockstep with the Foundation line while the contracts machine contract stays at 1.6.0.
 
 **Upgrade Notes**
 
-Version 0.6.0 is the Kit gate completion line. Projections whose authority does not live in the target root must declare an authorityBinding of kind external-root or caller-bytes and pin exactly 0.6.0.
+Version 0.7.0 is the projection closure builder line. Callers that previously assembled plan closures locally must import buildProjectionClosure and pin exactly 0.7.0. A plan closure ({path, type, sha256, mode} members) is not the harness computeResourceClosure resource closure ({path, role, exists, sha256} members) - the two shapes and purposes differ and are not interchangeable.
 <!-- release-skill:managed:end id=latest-release -->
 
 | Command | Purpose | Side effects |
@@ -47,7 +46,7 @@ Kit is the "engineering stage" layer, depending on the Harness and Contracts. It
 ## Installation and Minimal Example
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.6.0
+npm install --save-dev skill-family-engineering-kit@0.7.0
 npm exec -- skill-family-kit --help
 npm exec -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
 npm exec -- skill-family-kit adopt-plan --root <repo>
@@ -55,7 +54,15 @@ npm exec -- skill-family-kit projection --root <repo>
 npm exec -- skill-family-kit check --root <repo>
 ```
 
-The four commands above cover skeleton generation, read-only inventory, managed projection, and diagnostics respectively; a zero-install form is available via `npm exec --package=skill-family-engineering-kit@0.6.0 -- skill-family-kit --help`.
+The four commands above cover skeleton generation, read-only inventory, managed projection, and diagnostics respectively; a zero-install form is available via `npm exec --package=skill-family-engineering-kit@0.7.0 -- skill-family-kit --help`.
+
+### Public Profile SPI
+
+The `skill-family-engineering-kit/profile-spi` subpath exposes the stable Profile SPI v2 data surface. It exports `verifyProfile`, `verifyAdoptionDigests`, `assessOverridesPolicy`, `loadSpiDefinition`, `loadExtendedDescriptorSchema`, and `loadRuleBaselineCatalog`.
+
+The package carries three SPI JSON resources and the Contracts canonical `profile-descriptor.schema.json`. `profiles/spi` is the only handwritten source; projen mechanically projects those resources and the module into this subpath. The projection changes only the two public package imports and the local schema URL.
+
+`verifyProfile({ profileRoot })` is read-only and data-only. It refuses descriptor errors, missing resources, executable entrypoints, symlink/path escapes, core reverse dependencies, unverified adoption pins, and non-tightening overrides with stable `SPE0000` / `SPE1001`–`SPE1007` result codes. It never executes Profile-provided files. The Profile's domain meaning remains owned by the caller.
 
 ### Report sub-action
 

package/README.zh-CN.md

@@ -5,29 +5,28 @@
 
 # skill-family-engineering-kit
 
-<!-- release-skill:release-version: 0.6.0 -->
+<!-- release-skill:release-version: 0.7.0 -->
 
 开发与 CI 阶段使用的工程工具包。**恰好四个**顶层命令，没有第五个：
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.6.0** (2026-08-21)
+**0.7.0** (2026-08-21)
 
-本版为 check 命令新增入口契约门禁与受控 relock 事务子动作，新增外部冻结权威投影绑定（FG-3），并承载九类 check 诊断（审计整改 C2）。
+本版导出公共规范投影闭包 builder buildProjectionClosure（FG-4），调用方经一个公共入口即可构造 compileProjectionPlan 可直接接受的计划闭包，不再复刻 Kit 私有的排序、序列化与摘要算法。
 
 **新增**
 
-- 新增 check entries 子动作：runEntryContractCheck 与 checkEntriesAction 运行共享入口契约门禁（SFA-ENTRY-003/004/005/007 与 SFA-CONTEXT-001/002），作用于 skill-family.entry-contract.json 与 SKILL.md 字节；只诊断、零写入。
-- 新增 check relock 子动作：runRelock 与 relockAction 是零写入规则的唯一受控例外——一次失败关闭事务，精确写入两个受收容状态文档（.foundation/file-registry.json 与 skill-family.managed-file-lock.json），首次写入前做漂移校验，任何拒绝下零写入。
-- 新增外部冻结权威投影绑定（FG-3）：PROJECTION_AUTHORITY_BINDING_KINDS 冻结 external-root 与 caller-bytes；external-root 经严格不跟随读取器从独立的冻结目录重读每个权威源，caller-bytes 将调用方提供的 base64 权威字节绑定到声明的 sha256 摘要、完全不访问权威文件系统，使目标根内不存在伪造的本地权威事实。
+- 新增公共 skill-family-engineering-kit/profile-spi 子路径。它投影三个 Profile SPI JSON 资源与 Contracts canonical profile-descriptor.schema.json，导出 Schema 加载器、verifyProfile、采用 pin 校验和只收紧 overrides 检查。纯数据校验器遇到 pin 缺失、符号链接或路径越界时失败关闭，绝不执行 Profile entrypoint。
+- 新增 buildProjectionClosure：纯函数公共 builder，接受 {path, sha256, mode} 成员数组（可接受显式 type file），返回规范计划闭包 {digestAlgorithm sha256, digest, resourceCount, resources}，可原样作为 compileProjectionPlan 的 previousOwnedClosure 或 externalCandidateClosure；空数组返回合法的空闭包。
+- builder 与编译器闭包复验共享同一规范化与摘要事实源：确定性 path.localeCompare 排序、重复路径与便携路径冲突拒绝、sha256(JSON.stringify(normalizedResources)) 字节合同；全部拒绝在既有 projection plan input invalid 领域内失败关闭（SFC2004 invalid-manifest）。
 
 **变更**
 
-- check 诊断扩展为九类（新增版本单源一致性、公开边界校验、平台子集限制声明校验）；COMMAND_SIDE_EFFECTS 现记录 entries 与 relock 子动作语义。
-- 四个顶层命令（scaffold、adopt-plan、projection、check）保持不变；entries 与 relock 是 check 子动作，不是新命令。
+- compileProjectionPlan 入参合同不变，四个顶层命令（scaffold、adopt-plan、projection、check）不变；全部 0.6.0 既有输入仍编译为字节不变的计划。包版本随 Foundation 线锁步，Contracts 机器合同保持 1.6.0。
 
 **升级说明**
 
-0.6.0 是 Kit 门禁补齐线。权威不在目标根内的投影必须声明 kind 为 external-root 或 caller-bytes 的 authorityBinding，并精确锁定 0.6.0。
+0.7.0 是投影闭包 builder 线。此前在本地组装计划闭包的调用方必须导入 buildProjectionClosure 并精确锁定 0.7.0。计划闭包（成员 {path, type, sha256, mode}）不是 harness computeResourceClosure 的资源闭包（成员 {path, role, exists, sha256}）——两者形状与用途不同，不能互换。
 <!-- release-skill:managed:end id=latest-release -->
 
 | 命令 | 用途 | 副作用 |
@@ -48,7 +47,7 @@ Kit 是「工程阶段」层，依赖 Harness 与 Contracts。它只做四件事
 ## 安装和最小示例
 
 ```sh
-npm install --save-dev skill-family-engineering-kit@0.6.0
+npm install --save-dev skill-family-engineering-kit@0.7.0
 npm exec -- skill-family-kit --help
 npm exec -- skill-family-kit scaffold --root <empty-dir> --project-id my-project
 npm exec -- skill-family-kit adopt-plan --root <repo>
@@ -56,7 +55,15 @@ npm exec -- skill-family-kit projection --root <repo>
 npm exec -- skill-family-kit check --root <repo>
 ```
 
-以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.6.0 -- skill-family-kit --help`。
+以上四条命令分别覆盖生成骨架、只读盘点、受管投影与诊断；零安装形式可用 `npm exec --package=skill-family-engineering-kit@0.7.0 -- skill-family-kit --help`。
+
+### 公共 Profile SPI
+
+`skill-family-engineering-kit/profile-spi` 子路径提供稳定的 Profile SPI v2 数据表面，导出 `verifyProfile`、`verifyAdoptionDigests`、`assessOverridesPolicy`、`loadSpiDefinition`、`loadExtendedDescriptorSchema` 与 `loadRuleBaselineCatalog`。
+
+包内携带三个 SPI JSON 资源与 Contracts canonical `profile-descriptor.schema.json`。`profiles/spi` 是唯一手写真源；projen 将这些资源和模块机械投影到该子路径。投影只修改两个公共包导入和一个本地 Schema URL。
+
+`verifyProfile({ profileRoot })` 只读处理纯数据。遇到 descriptor 错误、资源缺失、可执行 entrypoint、符号链接或路径越界、反向依赖公共核心、未验证的采用 pin、未收紧的 overrides 时，以稳定 `SPE0000` / `SPE1001`–`SPE1007` 结果码失败关闭；它不会执行 Profile 提供的文件。Profile 的领域含义仍由调用方负责。
 
 ### 报告子动作
 

package/SECURITY.md

@@ -0,0 +1,33 @@
+# 安全策略（Security Policy）
+
+## 支持的版本
+
+| 版本 | 安全支持状态 |
+| --- | --- |
+| 0.1.x | 当前维护线：接受安全报告 |
+| 0.0.0 | 未发布的内部骨架版本，不在公开支持范围 |
+
+安全修复只承诺在最新的 0.1.x 线上提供；更早版本不回移修复。
+
+## 报告漏洞
+
+请勿通过公开 issue 直接披露未修复的安全漏洞。private workspace 仓永久
+private，不是公开报告渠道；请通过任一 public 发布镜像仓（例如
+`https://github.com/ifoohoo/skill-family-engineering-kit`）在 GitHub 上使用
+**Private vulnerability reporting**（仓库 Security 页签的
+"Report a vulnerability"）私下报告。
+
+报告时请尽量提供：
+
+- 受影响的包与版本（`skill-family-contracts`、`skill-family-harness-node`、
+  `skill-family-engineering-kit`）；
+- 可复现的最小步骤或概念验证；
+- 影响范围与利用前提。
+
+## 处置承诺
+
+- 收到报告后先确认受理，再按影响面排期修复；
+- 修复发布前不公开披露细节；
+- 修复随下一个补丁版本发布，并在该版本的变更记录中说明。
+
+本文件只描述漏洞报告渠道与支持版本；实时发布状态不属于本文件范围。