Repository navigation
Description
Current state: Accepted and closed by the requester on 2026-11-16. The accepted shared source-snapshot manifest landed on main through #360, #359 and #463. Knowledge PRs integrated after #359 changed 9–10 files each. Before #359, they changed 88–90. The evidence comment maps each acceptance item to tests and measurements on main ba233f7c. The closing comment records the acceptance.
Decision needed: None.
Next action: None under this issue. The manual re-pin after a squash merge stays a documented limit.
Problem
A small knowledge contribution should be easy to author, review and integrate. Today, repeated metadata and a repository-wide source revision make a change to one skill touch many unrelated files.
- PR #351 at
1694a0b5changes 86 files. Of its 79 generated skill JSON records, 78 change only the source pin; the remaining record contains the actual skill update. The incremental review documents the regeneration and the declaration burden. - The integration review on #342 reports 81–85 conflicting files in trial merges with other knowledge PRs, largely generated projections and shared views. Some PRs also edit the same handwritten owner, so real content conflicts must remain explicit.
Goal
Trim the contribution workflow so a single-skill change normally touches its canonical sources, its affected projection and a small, justified set of shared generated artifacts. Contributors should spend their effort on knowledge and evidence, rather than copying JSON, enumerating mechanical paths or resolving unrelated source-pin churn.
Scope
- Inventory the required authoring steps and fields. Keep human-authored knowledge, evidence judgments and truthful authorship separate from data that tools can derive.
- Automate mechanical metadata, hashes, generated views and declaration path lists through a documented workflow. Never infer or replace the actual model, effort, human contribution or exception decision.
- Remove repository-wide pin-only rewrites of unrelated skill records. Evaluate a shared provenance manifest, per-owner revisions/content identities, or another bounded design before choosing one. Explain the trade-offs, compatibility and migration.
- Preserve source snapshots, source/file hashes, traceable attribution, deterministic generation, stale-index detection and installed-wheel validation. Document and test provenance resolution after the supported merge workflow.
- Make the contribution guide and PR evidence concise: identify substantive changes, generated changes, commands and checks without duplicating the same facts across many files.
Acceptance
- Record a before/after single-owner example, including manual steps, files changed and generated-only churn. Afterward, unrelated owners' JSON records remain unchanged; every shared output touched has a documented reason.
- Demonstrate two parallel PRs changing different skill owners, integrate them in either order, and show that regeneration preserves both contributions without hand-editing unrelated generated records. Same-owner content conflicts are not silently discarded.
- A clean checkout can reproduce the artifacts; a second generation makes no changes. Negative controls still detect stale or tampered sources/projections and missing source resources.
- Existing retrieval/Collect contracts, resource resolution and clean-wheel checks remain compatible. Any necessary format migration is explicit and covered by tests.
- The helper produces complete, reviewable declaration paths while retaining accurate authorship and the current policy checks. Generated files are not assumed exempt from the knowledge-model policy. Any proposed policy change requires a separate explicit decision.
- Publish the short contributor workflow and measured reduction in contribution/review overhead.
Boundaries
This is a bounded contribution-tooling and representation improvement, related to #91 and #255. It does not accept new knowledge, settle existing PR blockers, change retrieval ranking, establish skill efficacy, or authorize paid experiments. Implementation design and any broader policy changes remain to be reviewed; creating this issue does not expand other issues' accepted scope.
Activity
amy-why-3459 commentedon Nov 5, 2026
Thanks for opening this with concrete evidence from #351 and #342 — the 78 pin-only skill JSON rewrites and the 81–85 conflicting generated files in trial merges make the contribution/review cost very clear.
A few notes on scope and acceptance so implementers stay aligned:
This looks like a well-bounded tooling/representation improvement related to #91 / #255, and it correctly does not expand other issues' accepted scope. Happy to review a design sketch or a minimal prototype PR that demonstrates the dual-owner merge case.
Dong1017 commentedon Nov 5, 2026
我来认领并推进 #355。
先核对当前生成链路、贡献步骤和在途 PR,再提交有明确取舍说明的最小实现:减少单个 owner 修改导致的无关 JSON/source pin 改写,保留快照、哈希、确定性生成、stale 检测和 wheel 资源校验。会补上双 owner 并行分支按两种顺序集成、同 owner 冲突、篡改/缺失资源等回归证据,以及机械 declaration 路径清单工具。
模型、effort、人类贡献和 exception 决定仍须显式提供,不修改现行知识模型政策;设计与实现提交 review 后再落地。
Dong1017 commentedon Nov 5, 2026
设计草案(供 review,尚未作为已接受方案落地):采用一个共享的 source snapshot manifest,owner JSON 只保存自身内容和资源哈希;catalog 读取时恢复现有完整 Git URL、commit 和 registry hash 接口。
取舍:
接下来做最小 prototype 与两个合并顺序的回归测试,提供 clean/shallow checkout、重复生成、缺失与篡改资源负例和实际文件数对比,再提交 PR review。声明路径 helper 只枚举路径与 head,作者事实与 exception 决定保持显式。
Dong1017 commentedon Nov 9, 2026
Design decision for scope item 3. Posted by Claude Code (claude-opus-5-5) through the Dong1017 account, on the account holder's explicit decision.
Accepted: the shared source-snapshot manifest described in the design comparison. One
knowledge/_provenance.jsonstores the full source commit and registry hash. Schema-v2 owner records keep only their own content and resource hashes. The catalog resolves them back into the existing schema-v1 public records.Why this option:
3a67f2456156f1071d4821e172a5bb55393f3f08, all 80 owner records pin1e87be46b8d080d439bb516ed9fa9092f8306f62. GitHub's compare reports that commit as diverged from main, with merge base6fefa0108232fcf210aa7c0f2ba3fa936439bd02, so the shipped pin is already not an ancestor of main after an ordinary squash. The manifest keeps this limit explicit, and the documented projection-only repair PR remains the remedy when ancestor resolution is needed.Rollout:
knowledge-model-policycan pass on its own; no exception is requested. The prototype commit stays in branch history.This decision does not check any acceptance item, name the accountable or goal-acceptance owners, change the knowledge-model policy, or close this issue.
Revert the shared-provenance prototype before reimplementation
Merge main into the #355 knowledge-workflow branch
knowledge: store generated records against a shared source snapshot (#…
knowledge: reject foreign records in a source-snapshot pack (#463)
Dong1017 commentedon Nov 16, 2026
Status refresh (2026-11-16). The accepted shared source-snapshot design has landed on main
ba233f7cb93b61e19fd07f6f18b6ae2c4b2a4efe. It shipped in three PRs:_provenance.json, the declaration-path helper and the contributor workflow.Evidence for each acceptance item:
Before/after single-owner example. See What changes per contribution. The test edit was one appended line in
performance-ceiling-analysis. With the old generator it changed 82 generated files: 80 records, the README and the coverage view. With the new generator it changes 3: that record,_provenance.jsonand the coverage view. The doc states why each shared output changes. Merged knowledge PRs show the same drop. knowledge: audit Infera serving-search result provenance #332, knowledge: distinguish Xe-Forge trial origin and timing #322, knowledge: audit DeepSeek C expert-cache byte validity #324 and knowledge: validate NInfer state and completion contracts #325 changed 88–90 files each. After prototype: reduce knowledge projection and declaration churn #359, Add source-bound TTS playout benchmark guidance #339 changed 9 files and Extend VLA observation-to-action benchmark guidance #342 changed 10: 6 canonical, 3 generated and the installed-resource count.Two parallel PRs on different owners.
tests/test_source_snapshot.pycovers this withtest_parallel_owner_edits_integrate_in_either_order(both orders) andtest_same_owner_divergent_edits_remain_an_explicit_conflict. Hostedfull-checkruns both. In practice, Extend VLA observation-to-action benchmark guidance #342 (inference-benchmark-design) was integrated on top of docs: anchor L1 weight demand against the checkpoint in performance-ceiling-analysis #351 (performance-ceiling-analysis). Only_provenance.jsonanddocs/skill-coverage.mdconflicted, and regeneration resolved them without hand-editing any record.Reproduction and negative controls. In CI,
test_generated_index_matches_current_sources_without_historical_git_objectsandtest_committed_view_matches_its_sourceskeep committed outputs current from a shallow checkout. These tests detect changed, added and removed source inputs and a tampered or missing snapshot:test_index_checks_drift_and_rejects_changed_or_added_source_inputstest_check_detects_tampered_or_missing_snapshotknowledge: reject foreign records in a source-snapshot pack #463 also rejects foreign records in a snapshot pack.
Compatibility and migration. Stored records moved to schema 2 in one explicit migration.
test_packaged_records_store_schema_two_and_resolve_to_schema_onechecks that all 80 records resolve to the unchanged schema-1 public records. Theinstalled-packagewheel checks pass on 3.10 and 3.11. The workflow doc's Stored format and Limits sections document the raw-format change.Declaration helper.
tools/knowledge_declaration_paths.pylists the head SHA and the protected, policy and generated paths, andtests/test_knowledge_declaration_paths.pytests it. It never supplies authorship, model, effort or exception decisions. Generated files remain protected paths, and this work did not change the knowledge-model policy. The Extend VLA observation-to-action benchmark guidance #342 and knowledge: reject foreign records in a source-snapshot pack #463 declarations used the helper.Workflow and measured reduction. The workflow is published on main as docs/knowledge-contribution-workflow.md. Item 1 has the measurement. Trial-merge conflicts dropped from the 81–85 files reported on Extend VLA observation-to-action benchmark guidance #342 to the 2 expected shared generated files. Reviewer time was not measured; file and conflict counts are the measure this issue's problem statement uses.
Known limit, documented in the workflow: after a squash merge, the snapshot pin is a branch commit that is not an ancestor of main. The next knowledge PR re-pins when it regenerates.
This comment records evidence. It does not check acceptance items or close the issue.
amy-why-3459 commentedon Nov 16, 2026
Thanks for refreshing the status block (2026-11-16). I see that the accepted shared source-snapshot design has landed on main via #360, #359 and #463, and that the evidence comment maps each of the six acceptance items to tests and measurements on
ba233f7c. Leaving the checkboxes unchecked until a goal-acceptance decision is the right call.Two points for that decision:
I am not accepting or closing the issue in this comment.
Dong1017 commentedon Nov 16, 2026
@amy-why-3459 thanks. Answers for the decision:
Tested in the post-squash state. A depth-1 clone of main
016c7c7df023944f0f46d8e777d6d31f1df1764cdoes not contain the snapshot pin23d27be8. In that clone, the following tests pass, and the catalog resolves all 80 records:test_packaged_records_store_schema_two_and_resolve_to_schema_onetest_generated_index_matches_current_sources_without_historical_git_objectstest_committed_view_matches_its_sourcesResolution reads only
_provenance.jsonand the stored records. The hash checks compare the current sources, not the pinned commit.Documented under Limits in the workflow doc. The packaged content resolves.
--checkand Git-backed SkillEval planning need the pinned commit, which a squash leaves outside main until the next knowledge PR re-pins.Predates this issue. Before prototype: reduce knowledge projection and declaration churn #359, all 80 records already pinned a squashed branch commit, as recorded in the design decision. trim & improve: reduce knowledge contribution cost and generated-file churn #355 did not add this residual and does not claim to remove it.
Reviewer time was not measured separately; file and conflict counts are the measure this issue uses. Closing as completed.