T-7V6K-import-from-github-and-source-picker

State: planning/proposed · Impact: high · Complexity: large

Goal

Import today reads a local directory only, so bringing in a skill someone published on GitHub means cloning it by hand first. This task adds a source picker — local directory, GitHub, or the user’s own harness skill directories — and closes the provenance gap the workflow-and-ux assessment names as P2-9: adoption stamps all six documented provenance keys instead of three, so a later change at the source can always be noticed.

Today

Location	Role today
`solutions/determined/experiences/agent-pants/app/pages/apps/agent-pants/import.vue`	One `Source` text field (a local path) plus a plugin field; no GitHub or harness-dir picker
`solutions/determined/experiences/agent-pants/app/pages/apps/agent-pants/import.guards.ts`	Pure decision helpers (`canReplace`, `isImportable`, `importSubset`, …); no source-kind logic
`solutions/determined/experiences/agent-pants/app/composables/useAgentSkillAdopt.ts`	Wraps `agentSkillGetAdoptPreview`/`agentSkillAdoptSkillsIntoVault`; `request.source` is always a local absolute path
`solutions/determined/crates/determined-agent-skills/src/lib.rs`	Calls `agent_adapt_core::adopt::adopt_skills` directly over the request’s `source`; no clone step
`solutions/agent-pants/crates/agent-adapt-core/src/adopt.rs`	Stamps `ap-source`, `ap-source-hash`, `ap-adopted-at`; `ap-format` and `ap-also-at` are stated deferrals, `ap-adopted-hash` is typed but never written or compared
`solutions/agent-pants/crates/agent-adapt-core/src/frontmatter.rs`	Types and round-trips all six `Provenance` keys; three ride unwritten
`solutions/agent-pants/crates/agent-adapt-core/src/corpus.rs`	`user_root()` resolves the well-known harness scan roots; no caller in agent-pants reaches it (only its `suspenders-core` mirror is called, from `solutions/ontological`)
`solutions/agent-pants/docs/vault/research/plugin-installed-skills.md`	Rules manager-installed skills never adoptable; the manager’s own registry, not a name pattern, is the discriminator
`packages/rust/fluent-git/`	Fluent git command builder; no clone verb
`packages/rust/easy-git/`	Typed query/worktree helpers over `fluent-git`; no clone verb
`packages/ts/easy-git/client.ts`	Typed `Git`/`AsyncGit` client over a shared verb table; a clone is reachable only through `raw()`
`solutions/agent-pants/packages/agent-pants/src/commands/adopt.ts`	CLI `adopt` command; sources are local paths resolved against cwd, no clone
`solutions/determined/experiences/agent-pants/app/components/ApPropertiesPanel.vue`	Renders every key `ap_provenance` sends; ready for the three unwritten keys once they exist
`solutions/agent-pants/docs/vault/tasks/adopt-docs-match-behaviour.md`	Vault note: adopt’s own docs promise a flat layout and six keys the core never writes (P2-9, doc half)
`solutions/agent-pants/docs/vault/tasks/adopt-hash-enables-divergence-check.md`	Vault note: `ap-adopted-hash` is declared and parsed, never written or compared (P2-9, design half)

Proposed

Import gains a source-kind picker: Local directory, GitHub (owner/repo[/path][@ref] or a full URL), and the user’s own harness skill directories, surfaced through corpus::user_root()’s existing scan and filtered by plugin-installed-skills.md’s ruling — no manager-owned tree is ever offered. The desktop resolves a GitHub source through a new adopt_from_git entry point in determined-agent-skills that clones or fetches the ref to a cache directory (a clone verb added to fluent-git or easy-git) and then runs the existing adopt_skills over that checkout. The CLI resolves the same source kind in TypeScript with @sksizer/easy-git before handing a local path to the WASM core, which cannot shell out. Every adopted note carries all six provenance keys: ap-source as <url>@<sha> for a GitHub source, ap-format naming the harness layout the picker or a heuristic detected, ap-source-hash and ap-adopted-hash from the existing hashing formula (the latter newly written, enabling the three-way unchanged/updated/refused: diverged comparison the design already describes), ap-adopted-at, and ap-also-at when the same content turns up at more than one scanned root. ApPropertiesPanel.vue renders every stamped key. The two vault notes describing the docs/behavior gap are rewritten to state the shipped six-key reality, or deleted once nothing in them is still true.

Approach

Add a clone/fetch verb: a Rust-side addition to fluent-git or easy-git used by adopt_from_git, and a TypeScript-side clone helper in @sksizer/easy-git for the CLI — decide whether the TS client gets a first-class clone verb on its shared table or stays on raw() for this one case.
determined-agent-skills: add adopt_from_git(vault, url, ref?, ...) that resolves the checkout to a cache directory, computes <url>@<sha>, and delegates to the existing agent_skill_adopt_skills_into_vault path over the checkout’s local path.
agent-adapt-core/src/adopt.rs: extend AdoptRequest/adopt_skills to accept an optional source URL and a format hint (from the picker or a per-source-kind default) and write ap-format and ap-source as <url>@<sha> when present; local-path adoption is unchanged.
Write ap-adopted-hash per adopt-hash-enables-divergence-check.md’s formula (projection::content_hash over the note with every ap- key stripped, plus the peer folder) and its three-way comparison, replacing the current directory-exists-or-force check.
Write ap-also-at by cross-referencing the current scan against every other scanned root when the same content is found at more than one.
Build the source picker (design from stories-agent-manager-workbench): a segmented control for Local / GitHub / Harness directory in import.vue; the GitHub tab parses owner/repo[/path][@ref] and full URLs in import.guards.ts; the harness-directory tab lists corpus::user_root() results filtered per plugin-installed-skills.md.
commands/adopt.ts: a flag that clones a GitHub source via @sksizer/easy-git to a cache directory before resolving the existing local-adopt path.
Rewrite adopt-docs-match-behaviour.md and adopt-hash-enables-divergence-check.md in place to the shipped behavior, or delete each once every acceptance criterion it states is met.
Verify: Rust tests for the new hash and three-way comparison and for a git-sourced provenance stamp; a Playwright import spec against a local bare-repo fixture (no live network in CI); a CLI test for the clone-before-adopt path.

Areas

Area	Note
`solutions/determined/experiences/agent-pants/app/pages/apps/agent-pants/import.vue`	Mount the source picker; branch on source kind
`solutions/determined/experiences/agent-pants/app/pages/apps/agent-pants/import.guards.ts`	Source-kind guards: parse GitHub refs, filter manager-owned dirs
`solutions/determined/experiences/agent-pants/app/composables/useAgentSkillAdopt.ts`	Preview/adopt calls carry the resolved source
`solutions/determined/crates/determined-agent-skills/src/lib.rs`	New `adopt_from_git` entry point
`solutions/agent-pants/crates/agent-adapt-core/src/adopt.rs`	Write `ap-format`, `ap-adopted-hash`, `ap-also-at`; three-way re-adopt comparison
`solutions/agent-pants/crates/agent-adapt-core/src/corpus.rs`	Call `user_root` from the new harness-directory source kind
`packages/rust/easy-git/src/`	Add a clone/fetch verb
`packages/ts/easy-git/client.ts`	Clone helper for the CLI’s git-sourced import
`solutions/agent-pants/packages/agent-pants/src/commands/adopt.ts`	Clone-before-adopt for a GitHub source
`solutions/determined/experiences/agent-pants/app/components/ApPropertiesPanel.vue`	Render the three newly-written provenance keys
`solutions/agent-pants/docs/vault/tasks/adopt-docs-match-behaviour.md`	Rewritten to the shipped behavior, or deleted
`solutions/agent-pants/docs/vault/tasks/adopt-hash-enables-divergence-check.md`	Rewritten to the shipped behavior, or deleted
`solutions/determined/products/agent-pants/tests/e2e/import-source-picker.e2e.ts`	Playwright spec over the GitHub and harness-directory source kinds

Acceptance criteria

AC-1: The import page shows a Local / GitHub / Harness directory picker, matching the design in stories-agent-manager-workbench.
AC-2: Importing owner/repo/path@ref clones to a cache directory and the adopted note’s ap-source reads <url>@<sha>.
AC-3: The harness-directory source kind lists only trees the manager’s own registry does not own, per plugin-installed-skills.md.
AC-4: An adopted note carries all six provenance keys, and ApPropertiesPanel.vue renders every one that is present.
AC-5: Re-adopting an untouched source reports unchanged and writes no bytes; re-adopting after only the source moved reports updated; re-adopting after only the note was hand-edited reports unchanged; re-adopting after both moved is refused: diverged.
AC-6: adopt-docs-match-behaviour.md and adopt-hash-enables-divergence-check.md each either state the shipped six-key, three-way behavior or no longer exist.
AC-7: cargo test -p agent-adapt-core and the new import Playwright spec pass.

Out of scope

The CLI’s --as/--promote flags, unimplemented by design per commands/adopt.ts’s own module doc.
The desktop request’s missing skills subset and per-note --overwrite (desktop-adopt-reaches-the-full-request); a separate gap, not created by this task.
A live network fetch in CI; the GitHub source kind is exercised against a local bare-repo fixture.

Dependencies

T-I71M-stories-agent-manager-workbench supplies the source-picker and provenance-panel design.
T-MJWQ-oss-skill-fixtures-corpus: the vendored corpus this import path will exercise once it lands.
solutions/agent-pants/docs/vault/research/plugin-installed-skills.md: the manager-owned exclusion rule the harness-directory picker must honor.

Discovery context

From the user’s planning request of 2026-09-07. The provenance gap is P2-9 in solutions/agent-pants/docs/vault/design/workflow-and-ux-assessment.md, split into a doc half (adopt-docs-match-behaviour.md) and a design half (adopt-hash-enables-divergence-check.md); both are folded into this task rather than tracked separately. The harness-directory source kind follows the ruling in solutions/agent-pants/docs/vault/research/plugin-installed-skills.md.

Depends on

T-I71M-stories-agent-manager-workbench

← Back to Tasks