feat(analysis): add harness component snapshots

[U1oSun]

Summary

Add deterministic, privacy-safe Qoder project component snapshots and bounded diffs for Rules, Skills, Hooks, Commands, and Workflows.

Why

• Issue/Story: Roadmap LC-02 (no separate GitHub issue found)
• User or maintainer outcome: Maintainers and later loop capabilities can bind evaluation and recovery evidence to an exact, content-addressed project harness baseline without claiming runtime activation.

Traceability and Scope

• Spec/ADR, if applicable: docs/specs/2026-08-02-harness-component-snapshot-v1.md
• Acceptance criteria addressed: HCS-AC-1 through HCS-AC-10
• Canonical owners changed: scripts/harness-component-snapshot/ owns the capability; docs/ARCHITECTURE.md records the route; Qoder project inventory gains a collection allowlist.
• Explicit non-goals: Providers other than Qoder, user/global or plugin assets, MCP/Memory/subagent collection, runtime activation inference, mutation or restore execution, and root CLI registration.

Change Type

• Feature
• Bug fix
• Tests only
• Documentation/community
• Refactor with no intended behavior change
• Dependency, packaging, or infrastructure

Test and Review Evidence

Check	Result
node --test test/harness-component-snapshot.test.mjs test/harness-component-snapshot-cli.test.mjs	21 passed, 0 failed, 0 skipped
node --test test/doc-link-graph.test.mjs	6 passed
npm test	1,288 passed, 0 failed, 1 existing platform skip
npm run pack:verify	Passed: 458 npm entries, 480 runtime ZIP entries
git diff --check origin/main...HEAD	Passed
Independent contract/adversarial review	No remaining P1/P2 findings

Manual or visual evidence: Not applicable; this is a JSON automation and direct CLI capability with subprocess coverage.

Risk and Recovery

• Compatibility and cross-platform impact: Existing inventory behavior remains the default unless a caller supplies the new collection allowlist. Route normalization rejects absolute and drive-relative Windows forms, and portable fixtures cover Windows, macOS, and Linux forms.
• Package, plugin, schema, or generated-file impact: Adds a versioned HarnessComponentSnapshotV1 capability and shipped CLI modules. No generated files or dependency changes.
• Rollback or recovery path: Revert commit d053275. Snapshot rollback references are deliberately non-authorizing and cannot mutate a workspace.
• Residual risk or unverified boundary: Initial upstream CI is pending. The v1 surface is Qoder-project-only and intentionally remains outside the root CLI registry.

AI Involvement

• Level: Generated
• Human review and validation: UIOSUN directed the LC-02 scope and approved publication. The final commit was independently reviewed, rebased onto current main, and validated with focused, full-suite, documentation-link, package, and diff checks.

Checklist

• I followed AGENTS.md, CONTRIBUTING.md, and the relevant canonical-owner guidance.
• The change is focused and does not include unrelated local or generated state.
• Tests and documentation match the behavior actually delivered.
• Markdown links were checked when documentation moved or changed.
• Cross-platform behavior was considered for Windows, macOS, and Linux.
• Package/runtime verification was run when shipped files or dependencies changed.
• User-facing or compatibility changes are recorded in CHANGELOG.md. (Not applicable: this additive v1 capability is not registered in the root CLI and changes no existing user-facing behavior.)
• I have the right to contribute this work under the repository's MIT License.

[Copilot]

Pull request overview

该 PR 落地了一个能力私有（capability-owned）的 HarnessComponentSnapshotV1：为 Qoder 项目范围 的 Rules / Skills / Hooks / Commands / Workflows 生成确定性、隐私安全、可校验（digest/rollback ref）的组件快照，并提供有界 diff 与非授权的 rollback-reference 解析；同时通过 agent-customize 增加“项目集合 allowlist”以确保只采集明确在范围内的资产，符合所述 LC-02 v1 读面切片与 spec 约束。

Changes:

• 新增 scripts/harness-component-snapshot/：contract（canonical/digest/route safety）、snapshot 组装、bounded diff、rollback-reference resolution，以及 direct CLI（create/validate/diff/resolve）。
• agent-customize 的 Qoder provider 支持 projectCollections allowlist，并在非 Qoder provider 上显式拒绝该参数。
• 增加端到端 fixture + contract/CLI 测试与架构/规格文档路由更新。

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/harness-component-snapshot.test.mjs	覆盖快照确定性、隐私边界、hook/skill revision 维度、populationRef 约束、有界 diff、校验与 rollback-reference 行为。
test/harness-component-snapshot-cli.test.mjs	覆盖 direct CLI help/strict parsing、JSON stdout、stderr 不回显路径/不可信字段、各子命令回归。
test/fixtures/harness-component-snapshot/project/scripts/check.mjs	fixture：用于验证 hook script 纳入 revision 且不泄露内容。
test/fixtures/harness-component-snapshot/project/AGENTS.md	fixture：用于验证相对路径 route 与证据读取边界。
test/fixtures/harness-component-snapshot/project/.agents/workflows/handoff.json	fixture：包含绝对路径哨兵，验证隐私不泄露（只保留摘要）。
test/fixtures/harness-component-snapshot/project/.agents/skills/handoff/SKILL.md	fixture：用于 skills 采集/树 revision 行为覆盖。
scripts/harness-component-snapshot/snapshot.mjs	核心：workspace 边界校验、Qoder inventory 完整性探测、组件证据读取与 revision、workflow 扫描与快照组装。
scripts/harness-component-snapshot/rollback.mjs	非授权 rollback-reference 解析与解析结果契约。
scripts/harness-component-snapshot/README.md	能力说明与 direct CLI 用法，链接到 spec。
scripts/harness-component-snapshot/index.mjs	公共导出面：contract/create/diff/resolve。
scripts/harness-component-snapshot/diff.mjs	有界、确定性 diff（added/removed/changed/unchanged）与 digest。
scripts/harness-component-snapshot/contract.mjs	v1 contract：canonical stringify、route 规范化、ID/rollback ref、snapshot 校验与 digest。
scripts/harness-component-snapshot/cli.mjs	direct CLI：严格参数解析、stdout JSON、stderr 稳定 code 且不回显路径/不可信字段。
scripts/agent-customize/providers/qoder.mjs	增加 projectCollections allowlist 支持，按集合选择性采集 hooks/skills/rules/commands/agents/mcps。
scripts/agent-customize/inventory.mjs	非 Qoder provider 禁止 projectCollections，避免误用/误期望。
docs/specs/2026-08-02-harness-component-snapshot-v1.md	规格：AC（HCS-AC-1..10）、非目标、风险与证据链。
docs/ARCHITECTURE.md	记录能力 owner 与路由/边界（不注册 root CLI、只组合 allowlisted agent-customize 集合等）。

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.