Repository navigation
Conversation
… version `dokimi catalog provenance --root DIR --upstream CHECKOUT|--upstream-manifest FILE` reports, for each skill under DIR, the upstream skill and version it copies, how many commits and months behind upstream head it is, and whether it was edited. Offline: upstreams are named by the caller (local git checkouts, or a dokimi.upstream.v1 JSON manifest). dokimi ships no upstream list. A copy matches by git blob sha against the upstream history first, then by frontmatter name and word Jaccard similarity >= 0.8 (the threshold of the corpus study). The git reads use the same hardened wrapper as `catalog check`. Findings (upstream-stale, license-dropped, risk-inherited) come in a follow-up. Signed-off-by: Nikolay Petrov <nikolay.a.petrov@intel.com>
CLI interface change detectedThis PR changes dokimi's user-facing CLI surface (commands and/or options): + added command `dokimi catalog provenance`
+ option `--format`
+ option `--help/-h`
+ option `--root`
+ option `--upstream`
+ option `--upstream-manifest`Updated on every push; the |
|
✅ OpenCodeReview: Review complete: 0 finding(s) across 1 selected item(s). CI at Review details
|
|
|
||
| def blob_sha(raw: bytes) -> str: | ||
| """The git blob sha of ``raw``: what ``git hash-object`` prints for the same bytes.""" | ||
| return hashlib.sha1(b"blob %d\0" % len(raw) + raw, usedforsecurity=False).hexdigest() |
There was a problem hiding this comment.
Must-fix — Impact: byte-identical copies from SHA-256 Git repositories fail exact matching and can be reported as edited or unmatched. Trigger: use a checkout initialized with git init --object-format=sha256 as --upstream. Evidence: _head_blobs and _history retain Git's 64-character SHA-256 object IDs, whereas Index.match always looks up this 40-character SHA-1 digest. load_checkout accepts that repository without detecting or normalizing its object format. Normalize indexed blob keys from the bytes read (while retaining native IDs for cat-file), or otherwise handle the object format explicitly; also review the fixed-width _ZERO_SHA deletion check. Workaround: use a content manifest or a SHA-1 checkout. Severity: medium because this silently breaks the core matching verdict for a concrete repository format accepted by the public checkout contract.
| """The upstream version a copy with bytes ``raw`` and frontmatter ``name`` came from, or None.""" | ||
| exact = self._by_blob.get(blob_sha(raw)) | ||
| if exact: | ||
| best = min(exact, key=lambda v: (not v.head, v.behind if v.behind is not None else 1 << 30, v.upstream.order)) |
There was a problem hiding this comment.
Must-fix — Impact: duplicate-content manifest versions can report the wrong origin commit/date and overstate months behind. Trigger: within one manifest, list two non-head entries with identical content, dated January and March, with January first. Evidence: both have behind=None and the same upstream.order, so this key ties and min() selects January, contradicting the documented “newest such version” rule. The similar-match ranking also ignores dates when manifest candidates tie. Use known version dates to resolve recency within a manifest, and add a duplicate-content regression test. Workaround: list manifest versions newest first. Severity: medium because this silently produces materially incorrect provenance metrics for a bounded input class.
| log = _git(root, "-c", "core.quotepath=off", "log", "--raw", "--no-abbrev", "--no-renames", "--full-history", | ||
| "--format=C %H %cI", "HEAD", "--", _SKILL_PATHSPEC) |
There was a problem hiding this comment.
Must-fix — Impact: historical merge-resolution versions are omitted, and commits-behind can undercount file changes. Trigger: resolve a SKILL.md conflict with content unique to the merge, then modify that file in a later commit and match a copy of the resolution. Evidence: under Git's default merge-diff behavior, log --raw does not emit merge diffs; --full-history changes traversal, not that behavior. first_seen therefore never receives the resolution blob, and _head_blobs only recovers current HEAD. Explicitly collect merge changes with matching parsing/count deduplication, and test a historical conflict resolution. Workaround: supply the missing content in a manifest, though its commit count remains unknown. Severity: medium because normal merge histories yield incorrect exact-match results and drift counts, limited to this command.
There was a problem hiding this comment.
The merge diffs now count a merged change twice.
v1 on main, a branch edits SKILL.md to v2, merge --no-ff: a copy of v1 is 2 commits behind for one edit (the branch commit and the merge's first-parent diff), while git log -- skills/pdf/SKILL.md gives 1. Every merged PR doubles behind.
Suggestion: count a merge in touches only when its blob is new (a conflict resolution), and add the v1 case to the merge test.
| head_raw = data.get("head") | ||
| head: dict[str, Any] = head_raw if isinstance(head_raw, dict) else {} | ||
| upstream = Upstream( | ||
| name=name.strip(), order=order, head_commit=head.get("commit"), |
There was a problem hiding this comment.
Must-fix — Impact: malformed manifest input crashes the CLI with a traceback and infrastructure exit code 5 instead of an actionable input error (exit 2). Trigger: set head.commit to 123, or set a matched skills entry's commit to 123. Evidence: load_manifest passes both commit fields through without checking their types; upstream_rows and to_row later apply [:12], raising TypeError on integers. Validate both optional commit fields as strings or null before constructing the objects, with tests for both locations. Workaround: omit these fields or provide strings. Severity: medium because a bounded external-input validation failure prevents the entire requested report.
|
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #838 +/- ##
==========================================
- Coverage 95.75% 95.65% -0.10%
==========================================
Files 423 426 +3
Lines 56416 56843 +427
Branches 9714 9783 +69
==========================================
+ Hits 54019 54375 +356
- Misses 1489 1535 +46
- Partials 908 933 +25
🚀 New features to boost your workflow:
|
…ns and duplicate bytes - A sha-256 checkout prints 64-hex blob ids, so no byte-identical copy matched exactly. A copy's bytes are now looked up under both the sha-1 and the sha-256 blob id. - `log --raw` prints no diff for a merge commit, so a SKILL.md version a merge wrote was never indexed and commits-behind was short. Use --diff-merges=first-parent. - Several versions with identical bytes: the newest commit date wins the exact match (it was the first listed), as the module docstring says. Signed-off-by: Nikolay Petrov <nikolay.a.petrov@intel.com>
…, as documented The newest-date key ranked above the upstream order, so a later-dated upstream beat an earlier one on the command line. Keep the date as the tie-break within one upstream. Signed-off-by: Nikolay Petrov <nikolay.a.petrov@intel.com>
vchamarthi
left a comment
There was a problem hiding this comment.
🔴 Changes needed: 3 must-fixes, 3 nits · reviewed cdf421f
Next: @napetrov: fix the 3 must-fix findings and answer 4 open threads from exai-bot; then push for a re-review. 3 nits optional.
Blocking
- Still holds on this head: thread by exai-bot –
--upstreamon agit init --object-format=sha256checkout gives a byte-identicalSKILL.mdassimilar,edited: true, notexact. - Still holds on this head: thread by exai-bot – Two identical manifest entries dated January and March give the January date,
2026-01-01, not the newer2026-03-01. - Still holds on this head: thread by exai-bot – A copy of a
SKILL.mdconflict resolution givessimilar, notexact, because the merge diff is not in the history. - Still holds on this head: thread by exai-bot – A manifest with
head.commitset to123exits 5 with a traceback fromupstream_rows, not 2.
Verified on cdf421f: ✅ changed tests: 19 passed, fail on main · ✅ full suite with main merged in: 22238 passed · ✅ merges onto main ·
17 checks behind it, each with its evidence
| Area | What holds | How |
|---|---|---|
| Exact old version | The 19 changed tests pass on the head. They pin an exact match of an old version, 1 commit and 90 days behind head, and an exact match of head | tests on the head |
| Shallow and folder refusal | The changed tests pass on the head: a shallow clone is reported as seeing only its own history, and a plain folder inside a repository is refused | tests on the head |
| Duplicate upstream names | Two --upstream checkouts with one directory name are refused, as the changed tests pin |
tests on the head, edge input (collections) |
| Reverted version | A version that reappears after a later change is matched at its newest commit: 2026-04-01, 1 commit behind |
ran it |
| Months behind | A version dated after the head gives 0.0 months, and an empty summary gives a null median | ran it, edge input (numbers) |
| Naive dates | A manifest date without a zone is read as UTC | ran it, edge input (concurrency) |
| Missing root | A missing --root exits 2 with no traceback |
ran it, edge input (paths) |
| No upstream | Running without --upstream or --upstream-manifest exits 2 with no traceback |
ran it, edge input (cli) |
| Truncated manifest | A truncated manifest JSON is an input error | ran it, edge input (structured) |
| Manifest skills shape | A skills value that is not a list is an input error |
ran it, edge input (structured) |
| Name none | A copy with no name matches nothing by name, and to_row(None) gives match: null |
ran it, edge input (none) |
| Text without words | Empty and whitespace text, and CRLF text, tokenize as the ASCII words only | ran it, edge input (text) |
| Path outside root | _rel returns the absolute path for a skill outside --root. The raise the broken variant adds after that return, at catalog_provenance.py:24, never runs, so that variant behaves the same |
ran it, edge input (paths) |
| Months mutant | Negating if self.head: in months_behind is caught by the changed tests |
broke the code, tests caught it, edge input (numbers) |
| Root mutant | Negating the root check in cmd_catalog_provenance is caught by the changed tests |
broke the code, tests caught it, edge input (paths) |
| Whole suite | The whole test run passes with main merged in: 22238 passed, 0 failed | full suite, main merged in |
| Merge | The PR merges onto main with no conflict | merge onto main |
| key=lambda pair: (pair[0], pair[1].head, -pair[1].upstream.order, | ||
| -(pair[1].behind if pair[1].behind is not None else 1 << 30)), |
There was a problem hiding this comment.
Must-fix — the earlier recency fix does not cover similar matches. Impact: an edited copy can still report the older origin commit/date and inflated months behind. Trigger: in one manifest, list two non-head entries with identical V1 content, dated January 2025 and January 2026 (older first), then match V1 with one additional word such as scans. Evidence: both candidates have the same Jaccard score, head flag, upstream order and unknown behind count, so this max() returns the first entry; unlike _exact_rank, this key never compares dates. The added duplicate-manifest test exercises only the exact branch. Include known dates as the final within-upstream recency tie-break and add an edited-copy regression. Workaround: list manifest versions newest first. Severity: medium because supported manifest inputs silently produce incorrect provenance and drift metrics, limited to this command.
| log = _git(root, "-c", "core.quotepath=off", "log", "--raw", "--no-abbrev", "--no-renames", "--full-history", | ||
| "--diff-merges=first-parent", "--format=C %H %cI", "HEAD", "--", _SKILL_PATHSPEC) |
There was a problem hiding this comment.
Must-fix — Impact: repository configuration can remove the original skill version from the index and turn an unchanged old copy into similar, edited: true or unmatched. Trigger: use the two-version test checkout after git config log.showRoot false, then match V1. Evidence: Git suppresses the root commit's diff under that setting; this invocation lacks --root, so first_seen never receives V1, while _head_blobs recovers only V2. Explicitly pass --root and test that local configuration does not change the report. Workaround: set log.showRoot=true. Severity justification: medium because an accepted checkout silently produces an incorrect provenance verdict.
| if head.returncode: | ||
| raise ValueError(f"{root} is not a git checkout with a commit: --upstream takes a git checkout") | ||
| head_sha = head.stdout.strip() | ||
| head_date_text = _git(root, "log", "-1", "--format=%cI", head_sha).stdout.strip() |
There was a problem hiding this comment.
Must-fix — Impact: the read-only provenance command can execute a checkout-configured signature verifier. Trigger: an upstream with a signed commit, local log.showSignature=true, and gpg.program (or the format-specific verifier) pointing to an executable. Evidence: both this log call and _history inherit repository config without --no-show-signature; _git disables hooks, fsmonitor and transports, not signature verification. The existing guidance-history reader explicitly disables this behavior. Add --no-show-signature to both calls and a marker-executable regression test. Workaround: disable log.showSignature before inspection. Severity justification: high because inspecting a checkout treated as data can execute arbitrary code with the caller's privileges.
| if sha not in texts: | ||
| continue # a blob the clone does not hold |
There was a problem hiding this comment.
Must-fix — Impact: an incomplete upstream index is reported as history full, and a byte-identical historical copy can be labeled edited or unmatched without a completeness warning. Trigger: use a non-shallow --filter=blob:none clone whose old SKILL.md blob is unavailable offline. Evidence: _read_blobs skips cat-file --batch missing-object responses, this loop drops those versions, and history depends only on shallow status. Surface missing-object counts/completeness in the report or refuse the incomplete index with an actionable input error; add a blobless-clone regression test. Workaround: hydrate the relevant blobs before running provenance. Severity justification: medium because this silently changes matching verdicts for a bounded, accepted checkout class.
antonwolfy
left a comment
There was a problem hiding this comment.
Review at 185fee6. Matching, sha-256 handling and merge-resolved versions work, but several inputs a user can reach still crash or give a wrong verdict. The inline comments on the git config cases, the manifest types and the similar-match ranking should be fixed before merge. The ranking and summary also need tests. One doc nit.
What I ran, on a Linux review host at 185fee6:
make ci-local: 0 failed, 34 passed, 14 skipped; 22266 tests passed, 19 skipped; changed-line coverage 85%- Reproductions for the code findings, with a throwaway local git repo and no network.
- A mutation run: 58 mutants of the matcher, the summary and the text output against the new test file, 44 of which pass it.
Also open from other reviewers:
- I agree with @vchamarthi's points on a missing
--upstreamdirectory and on"head": "true"in a manifest. New evidence:--upstream does-not-existexits 5 withFileNotFoundError, and"head": 1exits 0 withat_head: false.
Bot points I checked that no longer apply at this head (3)
- exai-bot's point on SHA-256 repositories does not apply:
Index.matchlooks up both the sha-1 and the sha-256 blob id, and a byte-identical copy matchesexactin a--object-format=sha256checkout. - exai-bot's point on merge-resolved versions does not apply:
_historypasses--diff-merges=first-parent, and a copy of a conflict resolution matchesexactwith the rightbehindcount. - exai-bot's point on duplicate manifest versions does not apply to exact matches:
_exact_rankbreaks the tie by date, and a byte-identical copy gets the newer entry. The similar-match half is the inline comment on the ranking key.
| return None | ||
| words = _tokens(raw.decode("utf-8", errors="replace")) | ||
| scored = [(_jaccard(words, _tokens(v.text)), v) for v in candidates] | ||
| best_score, best = max( |
There was a problem hiding this comment.
The ranking key and the summary are not pinned by any test. Mutation check on the new test file: dropping the head, -order or -behind term of this max key, the not version.head or behind term of _exact_rank, changing >= to > at the 0.8 threshold (upstream.py:176), or replacing the median or the at_head, edited, similar and unmatched counts in summary all pass the full file (44 of 58 mutants pass). These lines decide which upstream, at_head, behind_commits and behind_months a copy reports, and the headline summary.
Suggestion: add a test with two upstreams (or a head and an older version) holding the same words, one at exactly Jaccard 0.8, and assert the chosen upstream, at_head and each summary field on a catalog of one exact, one similar, one unmatched and one at-head skill.
| best_score, best = max( | ||
| scored, | ||
| key=lambda pair: (pair[0], pair[1].head, -pair[1].upstream.order, | ||
| -(pair[1].behind if pair[1].behind is not None else 1 << 30)), |
There was a problem hiding this comment.
The similar match still takes the older of two same-content manifest versions. I agree with exai-bot here; the exact path now ranks by date, this key does not. Manifest with two non-head entries of the same content, dated 2025-01-01 (listed first) and 2026-01-01, head dated 2026-06-01, and a copy that adds one word: the row is match: similar, commit: old, date: 2025-01-01, behind_months: 17.0. With the entries reversed it is commit: new, behind_months: 5.0, so the months depend on the listing order.
Suggestion: add the version date to the end of the key, as _exact_rank does, and a test for the edited-copy case.
| # --diff-merges=first-parent: a merge commit prints no diff by default, so a SKILL.md version that a merge | ||
| # resolved (or changed) would never be seen and the commits it counts as behind would be short. | ||
| log = _git(root, "-c", "core.quotepath=off", "log", "--raw", "--no-abbrev", "--no-renames", "--full-history", | ||
| "--diff-merges=first-parent", "--format=C %H %cI", "HEAD", "--", _SKILL_PATHSPEC) |
There was a problem hiding this comment.
log.showRoot=false in the checkout drops the original version from the index. I agree with exai-bot here; I reproduced it. A two-commit repo (v1 is the root, v2 edits it) lists both versions. After git config log.showRoot false the history holds only v2, so an unchanged copy of v1 is similar or unmatched, and the report still says history full.
Suggestion: add --root to this log call, and a test that sets log.showRoot=false on the fixture and still matches v1 exact.
| if head.returncode: | ||
| raise ValueError(f"{root} is not a git checkout with a commit: --upstream takes a git checkout") | ||
| head_sha = head.stdout.strip() | ||
| head_date_text = _git(root, "log", "-1", "--format=%cI", head_sha).stdout.strip() |
There was a problem hiding this comment.
Reading a checkout can run a program the checkout configures. I agree with exai-bot here; I reproduced it. A repo with a commit that has a gpgsig header, log.showSignature=true and gpg.program set to a marker script: load_checkout runs the script. Both log -1 --format=%cI here and the log in _history (upstream.py:252) do it, and the marker file is absent without the config. _git disables the fsmonitor, hooks and transports, but not this.
Suggestion: pass --no-show-signature to both calls (or -c log.showSignature=false in catalog_git._git, which also covers the other readers), and add a marker-script regression test.
| versions: list[Version] = [] | ||
| for path, sha in sorted(keys): | ||
| if sha not in texts: | ||
| continue # a blob the clone does not hold |
There was a problem hiding this comment.
A blob the clone does not hold is dropped, and the report still says history full. I agree with exai-bot here; New evidence: after removing the loose object of v1's SKILL.md from a two-commit repo, load_checkout returns only the v2 version, with history full. A byte-identical copy of v1 is then similar or unmatched with no sign that the index is incomplete. A blobless clone gives the same, since protocol.allow=never stops the lazy fetch. I simulated the partial clone by deleting the object; I did not build a --filter=blob:none clone.
Suggestion: count the skipped versions and either refuse with an InputError naming the missing blobs or report history: partial in the upstream row.
| head_raw = data.get("head") | ||
| head: dict[str, Any] = head_raw if isinstance(head_raw, dict) else {} | ||
| upstream = Upstream( | ||
| name=name.strip(), order=order, head_commit=head.get("commit"), |
There was a problem hiding this comment.
A non-string commit in a manifest crashes the command with exit 5. I agree with exai-bot here; I reproduced both locations. "head": {"commit": 123, ...} fails in upstream_rows and a skills entry with "commit": 123 fails in to_row, both with TypeError: 'int' object is not subscriptable and exit 5. A list commit does not crash and is written into the JSON report as a list. A non-string date ("date": 5) is dropped without a message, while "date": "garbage" exits 2.
Suggestion: raise InputError when head.commit or an entry's commit or date is neither a string nor null, and add a test for each location.
Signed-off-by: Anton Volkov <antonwolfy@gmail.com>
vlad-perevezentsev
left a comment
There was a problem hiding this comment.
Review at 21b99cc. Exact matching, the sha-256 lookup and the date order of identical manifest versions are right, but the points below still hold on this head, and the merge-diff fix now counts a merged change twice. New points are in the line comments.
Agreed with @exai-bot: log.showSignature can run a program the checkout configures; log.showRoot=false drops the root version; a blob a partial clone lacks still reads history full; a non-string manifest commit crashes; the similar match ignores dates. On merge-resolved versions, the fix overcounts behind; I added the case in its thread.
Agreed with @vchamarthi: a missing --upstream gives a traceback; "head": "true" reads as not head; the text columns are not pinned by tests; U+2028 in a path; \r in _unquote.
Agreed with @antonwolfy: the ranking and summary need tests; the rest matches the points above.
What I ran, at 21b99cc:
make ci-local --offline: 0 failed, 23 passed, 20 skipped; 22,213 tests passed, 72 skipped; changed-line coverage 85%.- A local upstream where v1 → v2 reaches main through
merge --no-ff: a copy of v1 is2 commitsbehind for one edit. - The same upstream with
log.showRoot false: the v1 copy turnssimilar.--upstreamon a missing path:FileNotFoundErrortraceback. - A catalog with a copy that has no
description, a copy with noname:, and a copy of a skill the upstream renamed and edited 3 times: the first is missing from the report, the second matches by its directory name, the third is1 commitsbehind.
Checked, no issues
- Exact matching: both sha-1 and sha-256 blob ids are looked up; identical manifest versions go to the newest date, identical bytes across upstreams to the first listed, as documented.
- Read-only git:
_gitkeeps hooks, fsmonitor, transports and the caller'sGIT_DIRout;input=is the only change there. - CLI and docs: the leaf is
FREE, theupstreamflag concept and the CLI snapshot are updated, the doc section matches the output, the changelog fragment is under Added, and the new files have the SPDX header.
| if not entry.loaded or entry.skill is None: | ||
| continue # a skill that does not load has no bytes to match: `catalog check` reports it |
There was a problem hiding this comment.
A copy that does not load leaves no trace in the report.
A SKILL.md with no description (or broken YAML) still has bytes to match, but it is skipped, and the header says 2 under <root> for three copies. A byte-identical copy of an upstream skill that has no description is never reported.
Suggestion: match these by their bytes too, or at least count them in summary (not_loaded) and print a line naming them.
| commits that touched each path (newest first). A deletion is a touch with no blob.""" | ||
| # --diff-merges=first-parent: a merge commit prints no diff by default, so a SKILL.md version that a merge | ||
| # resolved (or changed) would never be seen and the commits it counts as behind would be short. | ||
| log = _git(root, "-c", "core.quotepath=off", "log", "--raw", "--no-abbrev", "--no-renames", "--full-history", |
There was a problem hiding this comment.
A copy of a skill the upstream moved or deleted reads as only a little behind.
With --no-renames, behind counts only the old path. Upstream renames skills/old to skills/renamed and edits it 3 times: a copy of the old version is 1 commits, 2.0 mo behind (the delete), and nothing says the path is gone at head.
Suggestion: when the matched path is not in the head tree, say so in the row (e.g. removed_at_head: true), so behind is not read as the full drift.
| if not entry.loaded or entry.skill is None: | ||
| continue # a skill that does not load has no bytes to match: `catalog check` reports it | ||
| skill = entry.skill | ||
| match = index.match(skill.path.read_bytes(), skill.name) |
There was a problem hiding this comment.
A copy with no frontmatter name is matched by its directory name.
skill.name falls back to the directory, while upstream versions use the frontmatter name only. So skills/pdf/SKILL.md without name: is similar to upstream pdf, but an upstream version without name: never matches. The docs say "the same frontmatter name".
Suggestion: pass the copy's frontmatter name (None when absent), or document the fallback and use it on both sides.
antonwolfy
left a comment
There was a problem hiding this comment.
I pushed a commit per nit, up to 21b99cc, which fix the nit from my review:
21b99cc:dokimi/docs/external-content.md:460: sayscontentis the text of the file, hashed as UTF-8, and that line endings count.
make ci-local at 21b99cc: 0 failed, 34 passed, 14 skipped.
Not approving yet. Still open: the five bugs and the risk from my review; @vchamarthi on A missing --upstream directory raises FileNotFoundError with exit 5 instead of an input error (reproduced at this head); @vchamarthi on A manifest entry with "head": "true" is read as not head with no error (reproduced at this head).
vchamarthi
left a comment
There was a problem hiding this comment.
🔴 Changes needed: 1 must-fix · re-reviewed 21b99cc
Next: @napetrov: fix the 1 must-fix finding, answer 14 open threads from antonwolfy, exai-bot, vlad-perevezentsev and settle 1 open question; then push for a re-review.
Blocking
- Still holds on this head: thread by exai-bot – A manifest with
head.commit123givesTypeErrorfromupstream_rows(upstream.py:399), not an input error. - Still holds on this head: thread by exai-bot – Two identical non-head entries, dated 2025 (listed first) and 2026, give a similar copy the 2025 entry,
commit: old. - Still holds on this head: thread by exai-bot – With
log.showRoot falsein the checkout, a byte-identical copy ofv1issimilar, notexact. - Still holds on this head: thread by exai-bot – A checkout with
log.showSignature trueand agpg.programscript runs that script on--upstream: the marker file exists after the read. - Still holds on this head: thread by exai-bot – A checkout whose
v1blob is missing from the object store still reportshistoryfull. - Still holds on this head: thread by @antonwolfy – Changing
if best_score < SIMILAR_JACCARD:to<=still passes the changed tests, so no test pins the 0.8 boundary. - Still holds on this head: thread by @antonwolfy – Two identical non-head entries, dated 2025 (listed first) and 2026, give a similar copy the 2025 entry,
commit: old. - Still holds on this head: thread by @antonwolfy – With
log.showRoot falsein the checkout, a byte-identical copy ofv1issimilar, notexact. - Still holds on this head: thread by @antonwolfy – A checkout with
log.showSignature trueand agpg.programscript runs that script on--upstream: the marker file exists after the read. - Still holds on this head: thread by @antonwolfy – A checkout whose
v1blob is missing from the object store still reportshistoryfull. - Still holds on this head: thread by @antonwolfy – A skills entry with
commit123givesTypeErrorfromto_row(upstream.py:385). - Still holds on this head: thread by @vlad-perevezentsev – A copy whose bytes equal an upstream version with no
descriptionis absent from the rows. - Still holds on this head: thread by @vlad-perevezentsev – A copy of
v1at a path renamed and edited three times since readsbehind_commits: 1, the delete only, because--no-renamesfollows the old path. - Still holds on this head: thread by @vlad-perevezentsev – A copy with no
name:in its frontmatter still matchespdfby its directory name, assimilar, not unmatched. - Open question for @napetrov: A copy of
v1atskills/old/SKILL.md, after the skill moved toskills/renamedand was edited three times, readsbehind_commits: 1, the delete only, because--no-renames(upstream.py:252) follows the old path. Say indocs/external-content.mdwhich path the count follows, or count across a rename and state that.
Verified on 21b99cc: ✅ changed tests: 23 passed, fail on main · ✅ full suite with main merged in: 22860 passed · ✅ merges onto main ·
20 checks behind it, each with its evidence
| Area | What holds | How |
|---|---|---|
| Changed tests | The 23 changed tests pass on the head and fail on main, where the module does not exist: exact copies of an old version and of head, shallow and folder refusal, sha-256 matching, duplicate manifest versions, and zone-less dates | tests on the head |
| Local ci | make ci-local with main merged in exits 0 |
full suite, main merged in |
| Merge | The PR merges onto main with no conflict | merge onto main |
| Text helpers | _tokens keeps only ASCII words: empty, whitespace, CR and U+2028 text give no words, and Straße gives stra and e |
ran it, edge input (text) |
| Line endings | A CRLF copy of an LF manifest entry is similar and edited, as the docs say line endings count |
ran it, edge input (text) |
| Manifest shape | A truncated manifest is an input error | ran it, edge input (structured) |
| Manifest skills | A skills value that is an object, not a list, is an input error |
ran it, edge input (structured) |
| No upstream | Running catalog provenance with no --upstream or --upstream-manifest is an input error |
ran it, edge input (cli) |
| Missing root | A missing --root is an input error |
ran it, edge input (paths) |
| Path outside root | _rel returns the absolute path for a skill outside --root |
ran it, edge input (paths) |
| Months and summary | A version dated after the head gives 0.0 months, and an empty summary gives a null median | ran it, edge input (numbers) |
| None inputs | to_row(None) gives match: null, _norm_name(None) gives None, and an unnamed copy with unknown bytes matches nothing |
ran it, edge input (none) |
| Duplicate upstream names | Two upstreams with one name are refused with an input error | ran it, edge input (collections) |
| Zone-less dates | A manifest date with no zone is read as UTC | ran it, edge input (concurrency) |
| Sha-256 deletion | In a sha-256 checkout, a copy of v1 is exact and 2 commits behind, counting a later deletion; the deletion's 64-zero id changes no row |
ran it |
| Conflict resolution | A copy of a conflict resolution is exact at the merge commit's date |
ran it |
| Root check | Negating the root check in cmd_catalog_provenance (catalog_provenance.py:69) fails the changed tests |
broke the code, tests caught it, edge input (paths) |
| Exact ranking | Flipping the date order in _exact_rank (upstream.py:62) fails the changed tests |
broke the code, tests caught it |
| Sha-256 blob id | Hashing the copy without the git blob header in blob_sha256 (upstream.py:56) fails the changed tests |
broke the code, tests caught it |
| Reraise in _rel | The raise added after the return at catalog_provenance.py:24 never runs, so that variant behaves the same |
ran it, edge input (paths) |
| commits: list[tuple[str, str, list[tuple[str, str]]]] = [] | ||
| touches: dict[str, list[str]] = {} | ||
| for line in log.stdout.splitlines(): | ||
| if line.startswith("C "): | ||
| _, sha, date = line.split(" ", 2) | ||
| commits.append((sha, date, [])) | ||
| elif line.startswith(":") and commits and "\t" in line: | ||
| meta, _, path = line.partition("\t") | ||
| new_sha = meta.split()[3] | ||
| path = _unquote(path) | ||
| commits[-1][2].append((path, new_sha)) | ||
| touches.setdefault(path, []).append(commits[-1][0]) | ||
| return commits, touches |
There was a problem hiding this comment.
🔴 Must fix: A clean merge --no-ff of one branch edit counts the edit twice: a copy of the old version reads 2 commits behind, not 1.
Input: v1 on main, a branch commit that edits skills/pdf/SKILL.md to v2, then git merge --no-ff of the branch. A copy of v1 gives behind_commits: 2 on the head, expected 1: git log -- skills/pdf/SKILL.md lists one commit after v1. The --diff-merges=first-parent flag prints the merge's own diff, which repeats the branch's edit, so touches records the merge as a second touch. The docs say a full clone gives the exact count.
Also at: dokimi/docs/external-content.md:448.
Fix, run on 21b99cc: the failing case passes; tests and lint are no worse.
| commits: list[tuple[str, str, list[tuple[str, str]]]] = [] | |
| touches: dict[str, list[str]] = {} | |
| for line in log.stdout.splitlines(): | |
| if line.startswith("C "): | |
| _, sha, date = line.split(" ", 2) | |
| commits.append((sha, date, [])) | |
| elif line.startswith(":") and commits and "\t" in line: | |
| meta, _, path = line.partition("\t") | |
| new_sha = meta.split()[3] | |
| path = _unquote(path) | |
| commits[-1][2].append((path, new_sha)) | |
| touches.setdefault(path, []).append(commits[-1][0]) | |
| return commits, touches | |
| commits: list[tuple[str, str, list[tuple[str, str]]]] = [] | |
| for line in log.stdout.splitlines(): | |
| if line.startswith("C "): | |
| _, sha, date = line.split(" ", 2) | |
| commits.append((sha, date, [])) | |
| elif line.startswith(":") and commits and "\t" in line: | |
| meta, _, path = line.partition("\t") | |
| new_sha = meta.split()[3] | |
| path = _unquote(path) | |
| commits[-1][2].append((path, new_sha)) | |
| # A merge's first-parent diff repeats its branch's edit: keep the older commit, as git log does. | |
| last: dict[str, str] = {} | |
| for _, _, changes in reversed(commits): | |
| changes[:] = [(path, new_sha) for path, new_sha in changes if last.get(path) != new_sha] | |
| last.update(changes) | |
| touches: dict[str, list[str]] = {} | |
| for commit, _, changes in commits: | |
| for path, _ in changes: | |
| touches.setdefault(path, []).append(commit) | |
| return commits, touches |
Summary
First half of GitSkills item 7 (provenance and upstream drift). New read-only command; no existing output changes.
Files:
dokimi/external/upstream.py(matcher, git and manifest readers),dokimi/commands/catalog_provenance.py(the command),cli_flags.py(newupstreamconcept),catalog_git.py(_git(input=)), docs inexternal-content.md.Evidence
tests/test_catalog_provenance.py, 19 tests: exact old version, exact head, edited copy, below threshold, shallow clone, manifest, refused schema, two upstreams with one name, plain folder inside a repo, zone-less manifest dates.intel-skills(33 SKILL.md, full history),--upstream= the repo itself: 33 exact, all at head, 0.5 s. This checks the path and speed only; it is not a corpus result.--upstream R/vendor/acme(a plain folder inside repo R) reportedhistory full, R's head, copyexact, at head.After:
not a git checkout: --upstream takes the top level of a git checkout.TypeError: can't subtract offset-naive and offset-aware datetimes.After: the months are computed (zone-less dates read as UTC).
make ci-local: 0 failed, 34 passed, 14 skipped; package and Windows smoke pass; CLI snapshot current.Merge Danger
Door: one-way for the surface this adds: the command and flag names, the
dokimi.upstream.v1manifest schema and the JSON report fields. Additive, nothing else moves.Blast Radius: low. New command only. Shared code touched:
catalog_git._gitgets an optionalinput=argument (default unchanged); one concept added to the flag registry.Decisions
nullfor commits and months only.[a-z0-9]+, as in the x13 study. Non-Latin skills score near 0 on similarity; exact matches are unaffected. Follow-up with item 6 (multilingual).--upstreammust be the top level of a checkout: a folder inside another repository is refused, so it cannot pick up that repository's history.upstream-stalenote,license-dropped-from-upstreamwarn,risk-inherited-from-upstreamwarn).provenance.py, to avoid feat(provenance): optional version and provenance on tasks and question-set items #800 (feat(provenance), tasks and question sets).--show-toplevelon Windows (git for Windows path form); no Windows run covers the provenance command.Self-review:
pr-reviewlocal mode, 2 passes, lane L2; pass 1 found 2 blocking (fixed), pass 2 clean. Run by one session without subagents.🤖 Generated with Claude Code