Skip to content

trim & improve: reduce knowledge contribution cost and generated-file churn #355

Closed

Description

@Dong1017

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 1694a0b5 changes 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

  1. Inventory the required authoring steps and fields. Keep human-authored knowledge, evidence judgments and truthful authorship separate from data that tools can derive.
  2. 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.
  3. 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.
  4. 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.
  5. 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

  1. amy-why-3459 commented on Nov 5, 2026

    @amy-why-3459
    Collaborator

    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:

    1. Keep human vs mechanical fields strict. Automating hashes, generated views, and declaration path lists is valuable; model/effort/human-contribution/exception decisions must stay explicit and must not be inferred by tooling.
    2. Pin churn design choice needs an explicit trade-off write-up (shared provenance manifest vs per-owner revisions/content identities vs another bounded option), including compatibility, migration, and how provenance resolution works after the supported merge workflow — before landing a preferred design.
    3. Acceptance gate I would lean on hardest: two parallel PRs that touch different skill owners, merged in either order, with regeneration preserving both contributions and leaving unrelated owners' JSON records untouched; same-owner content conflicts must remain visible, not silently discarded.
    4. Policy boundary: generated files should not be assumed exempt from the knowledge-model policy; any policy change should be a separate explicit decision, as you already note.
    5. Evidence shape: a before/after single-owner example (manual steps, files changed, generated-only churn) plus a short contributor workflow with measured overhead reduction will make review much cheaper than debating abstract designs.

    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.

  2. added
    area:knowledgeKnowledge line: packs, skill library, knowledge admission
    kind:taskBounded delivery task with a delegated slice
    on Nov 5, 2026
  3. Dong1017 commented on Nov 5, 2026

    @Dong1017
    CollaboratorAuthor

    我来认领并推进 #355。

    先核对当前生成链路、贡献步骤和在途 PR,再提交有明确取舍说明的最小实现:减少单个 owner 修改导致的无关 JSON/source pin 改写,保留快照、哈希、确定性生成、stale 检测和 wheel 资源校验。会补上双 owner 并行分支按两种顺序集成、同 owner 冲突、篡改/缺失资源等回归证据,以及机械 declaration 路径清单工具。

    模型、effort、人类贡献和 exception 决定仍须显式提供,不修改现行知识模型政策;设计与实现提交 review 后再落地。

  4. Dong1017 commented on Nov 5, 2026

    @Dong1017
    CollaboratorAuthor

    设计草案(供 review,尚未作为已接受方案落地):采用一个共享的 source snapshot manifest,owner JSON 只保存自身内容和资源哈希;catalog 读取时恢复现有完整 Git URL、commit 和 registry hash 接口。

    取舍:

    • 逐 owner 查 Git 最后修改 commit 可减少普通编辑的 pin churn,但 registry 的全文件哈希仍会扩散;正常 squash 后原 source commit 被新的集成 commit 替代,下次生成又会改动已合并 owner。依赖旧 JSON 复用 pin 则使生成依赖历史产物及可能缺失的 Git objects。
    • 共享 manifest 将快照 commit 与 registry 哈希集中保存。一次显式格式迁移后,单 owner 改动只改该 JSON 和共享 manifest;不改变原有 owner 内容、证据判断、检索排序或模型政策。代价是原始投影格式升级,必须保留旧格式读取并测试 catalog/Collect/source-reader/wheel 的解析兼容。
    • manifest 仍可能在并行分支间冲突,但它是机械产物,应从已保留两边 canonical source 的集成 commit 重生成;同 owner 的正文冲突先人工解决,不能通过重生成掩盖。

    接下来做最小 prototype 与两个合并顺序的回归测试,提供 clean/shallow checkout、重复生成、缺失与篡改资源负例和实际文件数对比,再提交 PR review。声明路径 helper 只枚举路径与 head,作者事实与 exception 决定保持显式。

  5. Dong1017 commented on Nov 9, 2026

    @Dong1017
    CollaboratorAuthor

    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.json stores 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:

    • #359 reports that a one-owner edit changes 2 generated index files instead of 81, with no unrelated pin-only owner rewrites instead of 79. This is the author's synthetic measurement and still needs the acceptance evidence below.
    • Per-owner last-modified revisions still spread the registry digest to every record, and they make generation depend on Git history. Reusing pins from old JSON makes generation depend on earlier artifacts.
    • The squash cost is not new. On current main 3a67f2456156f1071d4821e172a5bb55393f3f08, all 80 owner records pin 1e87be46b8d080d439bb516ed9fa9092f8306f62. GitHub's compare reports that commit as diverged from main, with merge base 6fefa0108232fcf210aa7c0f2ba3fa936439bd02, 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:

    1. #360 (reader only) lands first. This answers the scope question in the #360 review: now that the representation is accepted, landing the reader before the migration is in scope.
    2. prototype: reduce knowledge projection and declaration churn #359 is then reconciled with main without a force-push. An admitted author will rewrite its protected-path content so the declaration is truthful and knowledge-model-policy can 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.

  6. Dong1017 commented on Nov 16, 2026

    @Dong1017
    CollaboratorAuthor

    Status refresh (2026-11-16). The accepted shared source-snapshot design has landed on main ba233f7cb93b61e19fd07f6f18b6ae2c4b2a4efe. It shipped in three PRs:

    Evidence for each acceptance item:

    1. 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.json and 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.

    2. Two parallel PRs on different owners. tests/test_source_snapshot.py covers this with test_parallel_owner_edits_integrate_in_either_order (both orders) and test_same_owner_divergent_edits_remain_an_explicit_conflict. Hosted full-check runs 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.json and docs/skill-coverage.md conflicted, and regeneration resolved them without hand-editing any record.

    3. Reproduction and negative controls. In CI, test_generated_index_matches_current_sources_without_historical_git_objects and test_committed_view_matches_its_sources keep 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_inputs
      • test_check_detects_tampered_or_missing_snapshot
      • the invalid-snapshot and invalid-stored-record cases

      knowledge: reject foreign records in a source-snapshot pack #463 also rejects foreign records in a snapshot pack.

    4. Compatibility and migration. Stored records moved to schema 2 in one explicit migration. test_packaged_records_store_schema_two_and_resolve_to_schema_one checks that all 80 records resolve to the unchanged schema-1 public records. The installed-package wheel checks pass on 3.10 and 3.11. The workflow doc's Stored format and Limits sections document the raw-format change.

    5. Declaration helper. tools/knowledge_declaration_paths.py lists the head SHA and the protected, policy and generated paths, and tests/test_knowledge_declaration_paths.py tests 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.

    6. 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.

  7. amy-why-3459 commented on Nov 16, 2026

    @amy-why-3459
    Collaborator

    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:

    1. Squash-merge re-pin limit. The updated Next action and the evidence comment treat the post-squash snapshot pin (a branch commit that is not an ancestor of main, re-pinned by the next knowledge PR) as a documented residual. Please confirm whether this satisfies scope/acceptance item 4's requirement to document and test provenance resolution after the supported merge workflow, or whether it is an accepted residual that does not block closure.
    2. Goal-acceptance owner. Decision needed currently allows "the requester, or a named goal-acceptance owner." The requester also delivered the implementation. If acceptance is not meant to be self-certified, please name the goal-acceptance owner explicitly before closing.

    I am not accepting or closing the issue in this comment.

  8. Dong1017 commented on Nov 16, 2026

    @Dong1017
    CollaboratorAuthor

    @amy-why-3459 thanks. Answers for the decision:

    1. Post-squash resolution (scope item 4). Resolution after the supported squash workflow is documented and tested. The non-ancestor pin is an accepted residual and does not block closure.
      • Tested in the post-squash state. A depth-1 clone of main 016c7c7df023944f0f46d8e777d6d31f1df1764c does not contain the snapshot pin 23d27be8. In that clone, the following tests pass, and the catalog resolves all 80 records:

        • test_packaged_records_store_schema_two_and_resolve_to_schema_one
        • test_generated_index_matches_current_sources_without_historical_git_objects
        • test_committed_view_matches_its_sources

        Resolution reads only _provenance.json and 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. --check and 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.

    2. Goal-acceptance owner. The requester, who holds the Dong1017 account, is the goal-acceptance owner and accepts this issue. What was self-certified and what was reviewed:

    Reviewer time was not measured separately; file and conflict counts are the measure this issue uses. Closing as completed.

  9. added
    status:acceptedThe decision owner accepted it in a recorded comment
    and removed
    status:proposedWaiting for the decision named in the status block
    on Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:knowledgeKnowledge line: packs, skill library, knowledge admissionkind:taskBounded delivery task with a delegated slicestatus:acceptedThe decision owner accepted it in a recorded comment

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions