Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
<!--
Copyright (C) 2026 Intel Corporation
SPDX-License-Identifier: Apache-2.0
-->

### Added

- **`catalog provenance` matches each skill copy to the upstream version it came from** — offline, from the `--upstream` git checkouts or `--upstream-manifest` files you name (dokimi ships no upstream list). A copy is matched by its git blob sha against the upstream history, then by frontmatter name and word Jaccard similarity ≥ 0.8. The report gives the origin skill and version, how many commits and months behind upstream head, and whether the copy was edited.
38 changes: 38 additions & 0 deletions dokimi/docs/external-content.md
Original file line number Diff line number Diff line change
Expand Up @@ -438,6 +438,44 @@ combine with `--format json`; any other misuse exits 2. From Python,
`dokimi.external.review_skill_dir(path)` returns the `SkillReview` of the one
skill in `path`.

### Provenance: which upstream a copy came from (`catalog provenance`)

A skill copied from another repository drifts from it: the upstream is updated and the
copy is not, or the copy is edited and drops the licence. `catalog provenance` matches each
loaded skill under `--root` to a version of an upstream you name, offline. Dokimi ships no
upstream list: give it the upstreams yourself.

- `--upstream CHECKOUT` (repeatable) is the top level of a local git checkout; a folder inside another repository is refused. Clone it yourself; a full clone
gives the exact count of commits behind, a shallow one says it sees only its own history.
- `--upstream-manifest FILE` (repeatable) is a JSON file of one upstream, for an upstream that
is not a git checkout. Its `schema` field is the version-1 upstream schema string shown here:

```json
{"schema": "dokimi.upstream.v1", "name": "acme-skills",
"head": {"commit": "2c5958e", "date": "2026-04-01T00:00:00+00:00"},
"skills": [{"path": "skills/pdf/SKILL.md", "content": "---\nname: pdf\n...", "head": true,
"commit": "9f1c2ab", "date": "2026-03-01T00:00:00+00:00"}]}
```

`content` is the text of the file, hashed as UTF-8; line endings count. `head`, `commit` and `date` are optional. The git blob
sha is computed from `content`, so a manifest and a checkout agree.

```text
$ dokimi catalog provenance --root ./my-plugin --upstream ~/src/acme-skills
# upstream acme-skills: head 446e0e560cff 2026-04-01, history full
# skills (2 under ./my-plugin: 1 exact, 1 similar, 0 unmatched; 1 edited; 0 at head; median 3.0 months behind)
skill match upstream version behind edited
skills/pdf-copy exact acme-skills:pdf/SKILL.md 88fa89b3fcc7 2026-01-01 1 commits, 3.0 mo no
skills/pdf-edit similar acme-skills:pdf/SKILL.md 88fa89b3fcc7 2026-01-01 1 commits, 3.0 mo yes
```

A copy is matched by its bytes first: an identical `SKILL.md` at the upstream head or in its
history is `exact` (not edited), and the newest such version is the one reported. Otherwise
an upstream version with the same frontmatter `name` and a word Jaccard similarity of at least
0.8 is `similar` (edited). Anything else is `unmatched`. `behind` counts the commits that
touched the file after the matched version, and the months run from that version's commit date
to the upstream head. `--format json` adds the upstreams, one row per skill and a `summary`.

## 2. The awareness half: question sets

A question set is `<questions-root>/<product_key>_golden.json`, in the format
Expand Down
13 changes: 13 additions & 0 deletions dokimi/docs/reference/cli-interface.json
Original file line number Diff line number Diff line change
Expand Up @@ -352,6 +352,19 @@
"subcommand_required": null,
"subcommands": {}
},
"provenance": {
"allow_abbrev": true,
"params": [
{"key": "--format", "action": "_StoreAction", "choices": ["'json'", "'text'"], "const": null, "default": "text", "group_key": null, "group_required": null, "hidden": false, "is_flag": false, "kind": "option", "nargs": null, "position": null, "required": false, "type": null},
{"key": "--help/-h", "action": "_HelpAction", "choices": null, "const": null, "default": "==SUPPRESS==", "group_key": null, "group_required": null, "hidden": false, "is_flag": true, "kind": "option", "nargs": 0, "position": null, "required": false, "type": null},
{"key": "--root", "action": "_StoreAction", "choices": null, "const": null, "default": null, "group_key": null, "group_required": null, "hidden": false, "is_flag": false, "kind": "option", "nargs": null, "position": null, "required": true, "type": null},
{"key": "--upstream", "action": "_AppendAction", "choices": null, "const": null, "default": null, "group_key": null, "group_required": null, "hidden": false, "is_flag": false, "kind": "option", "nargs": null, "position": null, "required": false, "type": null},
{"key": "--upstream-manifest", "action": "_AppendAction", "choices": null, "const": null, "default": null, "group_key": null, "group_required": null, "hidden": false, "is_flag": false, "kind": "option", "nargs": null, "position": null, "required": false, "type": null}
],
"path": "dokimi catalog provenance",
"subcommand_required": null,
"subcommands": {}
},
"routing": {
"allow_abbrev": true,
"params": [
Expand Down
10 changes: 10 additions & 0 deletions dokimi/dokimi/cli_flags.py
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,16 @@ class Concept:
note="The subject is a positional. --product, --library and --target name it, so new "
"commands do not use them.",
),
Concept(
name="upstream",
help="the upstream copies a skill is matched against (catalog provenance)",
canonical=(
Flag("--upstream", "CHECKOUT", "path", repeatable=True,
meaning="a local git checkout of an upstream; its history gives the versions"),
Flag("--upstream-manifest", "FILE", "path", repeatable=True,
meaning="a dokimi.upstream.v1 JSON manifest of one upstream"),
),
),
Concept(
name="catalog_impact",
help="the local base revision for catalog change selection",
Expand Down
1 change: 1 addition & 0 deletions dokimi/dokimi/cli_routes.py
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,7 @@ class Tombstone:
Leaf(("catalog", "show"), FREE),
Leaf(("catalog", "intents"), FREE),
Leaf(("catalog", "check"), FREE),
Leaf(("catalog", "provenance"), FREE),
Leaf(("catalog", "eval"), FREE),
Leaf(("catalog", "formats"), FREE),
Leaf(("catalog", "trigger-probe"), PAID),
Expand Down
3 changes: 2 additions & 1 deletion dokimi/dokimi/commands/catalog.py
Original file line number Diff line number Diff line change
Expand Up @@ -577,6 +577,7 @@ def register(sub, positive_int, eval_sub) -> None:
ts_p.add_argument("--out", required=True, help="Output JSON path")
ts_p.set_defaults(func=cmd_catalog_trigger_set)

from dokimi.commands import catalog_probe
from dokimi.commands import catalog_probe, catalog_provenance

catalog_probe.register(catalog_sub, positive_int)
catalog_provenance.register(catalog_sub)
119 changes: 119 additions & 0 deletions dokimi/dokimi/commands/catalog_provenance.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
# Copyright (C) 2026 Intel Corporation
# SPDX-License-Identifier: Apache-2.0

"""``catalog provenance``: which upstream version each skill copy under ``--root`` came from, and how far behind it is.

Read-only and offline: the upstreams are the caller's (``--upstream`` checkouts, ``--upstream-manifest`` files). The
matching is in :mod:`dokimi.external.upstream`; this module reads the catalog and prints the rows.
"""

from __future__ import annotations

import argparse
import json
from pathlib import Path

from dokimi import cli_flags
from dokimi.utils import InputError


def _rel(skill_dir: Path, root: Path) -> str:
try:
return skill_dir.relative_to(root).as_posix()
except ValueError:
return skill_dir.as_posix()


def _behind_text(row: dict) -> str:
if row["match"] is None:
Comment thread
vchamarthi marked this conversation as resolved.
Resolved
return "-"
if row["at_head"]:
return "at head"
commits = "" if row["behind_commits"] is None else f"{row['behind_commits']} commits"
months = "" if row["behind_months"] is None else f"{row['behind_months']} mo"
return ", ".join(part for part in (commits, months) if part) or "unknown"


def _text(report: dict) -> str:
summary = report["summary"]
lines = []
for up in report["upstreams"]:
head = f"head {up['head_commit']} {up['head_date'] or ''}".strip() if up["head_commit"] else "no head"
note = " (shallow clone: older versions are not seen)" if up["history"] == "shallow" else ""
lines.append(f"# upstream {up['name']}: {head}, history {up['history']}{note}")
median = summary["median_months_behind"]
lines.append(
f"# skills ({summary['skills']} under {report['root']}: {summary['exact']} exact, "
f"{summary['similar']} similar, {summary['unmatched']} unmatched; {summary['edited']} edited; "
f"{summary['at_head']} at head; median {'-' if median is None else median} months behind)"
)
lines.append("skill\tmatch\tupstream\tversion\tbehind\tedited")
for row in report["skills"]:
upstream_text = "-" if row["upstream"] is None else f"{row['upstream']}:{row['path']}"
version = "-" if row["commit"] is None else f"{row['commit']}{' ' + row['date'] if row['date'] else ''}"
if row["version"]:
Comment thread
vchamarthi marked this conversation as resolved.
Resolved
version = f"v{row['version']} {version}"
edited = "-" if row["edited"] is None else "yes" if row["edited"] else "no"
lines.append(
f"{row['skill']}\t{row['match'] or 'unmatched'}\t{upstream_text}\t{version}\t"
f"{_behind_text(row)}\t{edited}"
)
return "\n".join(lines)


def cmd_catalog_provenance(args: argparse.Namespace) -> None:
from dokimi.external import read_skill_manifest
from dokimi.external import upstream

root = Path(args.root)
if not root.is_dir():
raise InputError(f"--root is not a directory: {root}")
if not args.upstream and not args.upstream_manifest:
raise InputError("catalog provenance needs --upstream CHECKOUT (a git checkout) or "
"--upstream-manifest FILE: dokimi ships no upstream list")
index = upstream.build(args.upstream or (), args.upstream_manifest or ())
try:
entries = read_skill_manifest(root)
except ValueError as exc:
raise InputError(f"skills.yaml: {exc}") from exc
rows = []
for entry in entries:
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
Comment on lines +81 to +82

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

skill = entry.skill
match = index.match(skill.path.read_bytes(), skill.name)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

rows.append({"skill": _rel(skill.path.parent, root), "name": skill.name, **upstream.to_row(match)})
report = {
"root": str(root),
"upstreams": upstream.upstream_rows(index),
"skills": rows,
"summary": upstream.summary(rows),
}
if args.format == "json":
print(json.dumps(report, indent=2))
else:
print(_text(report))


def register(catalog_sub) -> None:
"""Add ``catalog provenance`` to the ``catalog`` group."""
prov_p = catalog_sub.add_parser(
"provenance",
help="For each skill under --root: the upstream version it copies, how far behind head, and whether it was edited",
)
prov_p.add_argument("--root", required=True, help="Local checkout of the skills to match")
cli_flags.add(
prov_p, "upstream", "--upstream", action="append", default=None, metavar="CHECKOUT",
help="A local git checkout of an upstream (its history gives the versions). Repeatable; the first one "
"wins a tie. Nothing is fetched: clone it yourself, full history for an exact count",
)
cli_flags.add(
prov_p, "upstream", "--upstream-manifest", action="append", default=None, metavar="FILE",
help="A JSON manifest of one upstream: {\"schema\": \"dokimi.upstream.v1\", \"name\", \"head\": {commit, date}, "
"\"skills\": [{path, content, head?, commit?, date?}]}. Repeatable",
)
prov_p.add_argument(
"--format", choices=["text", "json"], default="text",
help="text: one line per skill (default); json: the upstreams, one row per skill and the summary",
)
prov_p.set_defaults(func=cmd_catalog_provenance)
4 changes: 2 additions & 2 deletions dokimi/dokimi/external/catalog_git.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,12 @@
from .catalog_eval_inputs import task_dir


def _git(root: Path, *args: str) -> process.Completed:
def _git(root: Path, *args: str, input: bytes | None = None) -> process.Completed:
# The checkout is data: no fsmonitor, hook or lazy-fetch transport it configures may run,
# and a caller's GIT_DIR (as in a hook) must not swap in another repository.
return process.git(
"--no-pager", "-c", "core.fsmonitor=false", "-c", f"core.hooksPath={os.devnull}", "-c", "protocol.allow=never",
*args, cwd=root, env=process.Env.only([k for k in os.environ if k not in process.GIT_REPO_OVERRIDES], {
*args, cwd=root, input=input, env=process.Env.only([k for k in os.environ if k not in process.GIT_REPO_OVERRIDES], {
"GIT_TERMINAL_PROMPT": "0", "GIT_CONFIG_NOSYSTEM": "1",
"GIT_CONFIG_GLOBAL": os.devnull,
}),
Expand Down
Loading
Loading