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

Current state: Opened 2026-11-05 with measured evidence from #351 (78 of 79 generated skill records change only the source pin) and #342 (81–85 conflicting files in trial merges). An agent session claimed the Issue at 11:54 UTC and posted a design draft at 11:58 UTC proposing a shared source-snapshot manifest with per-owner content/resource hashes; that draft is explicitly not an accepted design. Two implementation proposals now exist as Draft PRs: #359, head d1d64da1, contains the shared-manifest prototype and author-reported synthetic single-owner churn/integration checks; #360, head c9b1608d, separates the backward-compatible trusted SkillEval reader prerequisite. The #359 body reports generated index changes falling from 81 files to 2 and unrelated owner rewrites from 79 to 0 for its synthetic example; these are recorded prototype measurements, not this synchronization's reproduction or Issue acceptance. Both PRs remain open and Draft. The shared representation/design and #359 protected-path authorship admission remain unresolved; #360 does not accept that design or cure #359's admission. All six acceptance items remain unchecked. @amy-why-3459's comment is design feedback, not acceptance.
Decision needed: Accept, revise or reject the shared source-snapshot manifest as the chosen approach for scope item 3, against the alternatives that item names, and name the accountable and goal-acceptance owners, which are unassigned. From the maintainers/requester.
Next action: The existing claiming session and reviewers reconcile the published design comparison, prototype measurements and reader-only prerequisite with the pending design/admission decisions before landing a representation change. Reuse #359/#360 rather than start duplicate implementation. The accountable and goal-acceptance ownership decision and remaining acceptance evidence stay separate.

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.