feat(intent): add reviewable skill provenance with lockfiles and frozen CI

.changeset/many-forks-cough.md

@@ -0,0 +1,13 @@
+---
+'@tanstack/intent': minor
+---
+
+Add consumer-managed `intent.lock` files for reviewing and pinning the exact skill content approved for a project.
+
+- Add `intent skills scan`, `diff`, `approve`, and `update` for inspecting drift, reviewing exact current text and binary summaries, and maintaining approved sources.
+- Track sources by `(kind, id)` so same-named workspace and npm packages remain distinct approvals.
+- Hash each skill’s `SKILL.md` plus supported `references/`, `assets/`, and `scripts/` files with deterministic SHA-256 content hashes.
+- Add frozen-mode enforcement for CI through `--frozen`, `INTENT_FROZEN`, and non-interactive `CI` detection. Frozen mode rejects missing or malformed lockfiles, unapproved source changes, hidden skill-bearing sources, and lockfile mutations.
+- When an `intent.lock` exists, reject drift during ordinary skill loading and agent catalog generation so interactive agents cannot silently consume content that differs from the approved state.
+- Validate manifests against the installed package identity, skill paths, and content hashes. Manifest metadata changes appear in lockfile diffs and require approval before frozen checks pass.
+- Export lockfile metadata types from `@tanstack/intent`.

benchmarks/intent/README.md

@@ -0,0 +1,19 @@
+# Intent Benchmarks
+
+## Lockfile Scan Baseline
+
+Run from the repository root:
+
+```sh
+pnpm --dir benchmarks/intent exec vitest bench --config ./vitest.config.ts ./lockfile-scan.bench.ts
+```
+
+Local baseline recorded on 2026-07-09:
+
+| Case              | Fixture                                                               |       Mean |
+| ----------------- | --------------------------------------------------------------------- | ---------: |
+| Clean lockfile    | 8 packages, 3 skills per package, 3 support files per skill at 1 KiB  |  9.2180 ms |
+| Changed skill     | Same fixture, one `SKILL.md` changed after approval                   |  9.1127 ms |
+| Large support set | 24 packages, 4 skills per package, 6 support files per skill at 8 KiB | 50.7923 ms |
+
+The fixture creates `intent.lock` with `intent skills approve --all --yes` before each scan. Re-run these cases after changing lockfile discovery or hashing and compare the same fixture means.

benchmarks/intent/helpers.ts

@@ -153,7 +153,7 @@ export function createTempDir(name: string): string {
   return mkdtempSync(join(tmpdir(), `intent-bench-${name}-`))
 }
 
-export function writeFile(filePath: string, content: string): void {
+export function writeFile(filePath: string, content: string | Buffer): void {
   mkdirSync(dirname(filePath), { recursive: true })
   writeFileSync(filePath, content)
 }

benchmarks/intent/lockfile-scan.bench.ts

@@ -0,0 +1,137 @@
+import { rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { afterAll, beforeAll, bench, describe } from 'vitest'
+import {
+  createBenchOptions,
+  createCliRunner,
+  createConsoleSilencer,
+  createTempDir,
+  writeFile,
+  writeJson,
+  writePackage,
+} from './helpers.js'
+
+type LockfileFixture = {
+  root: string
+  runner: ReturnType<typeof createCliRunner>
+}
+
+type FixtureOptions = {
+  changedSkill?: boolean
+  packageCount: number
+  skillCount: number
+  supportFileCount: number
+  supportFileSize: number
+}
+
+function createFixture(name: string, options: FixtureOptions): LockfileFixture {
+  const root = createTempDir(name)
+  const packageNames = Array.from(
+    { length: options.packageCount },
+    (_, index) => `@bench/lock-${index}`,
+  )
+  writeJson(join(root, 'package.json'), {
+    name: `intent-lockfile-${name}-benchmark`,
+    private: true,
+    intent: { skills: packageNames },
+  })
+
+  for (const packageName of packageNames) {
+    const skills = Array.from(
+      { length: options.skillCount },
+      (_, index) => `skill-${index}`,
+    )
+    writePackage(join(root, 'node_modules'), packageName, '1.0.0', { skills })
+    const packageRoot = join(root, 'node_modules', ...packageName.split('/'))
+    for (const skillName of skills) {
+      const skillDir = join(packageRoot, 'skills', skillName)
+      for (let index = 0; index < options.supportFileCount; index++) {
+        const directory = ['references', 'assets', 'scripts'][index % 3]!
+        const extension = directory === 'scripts' ? 'mjs' : 'dat'
+        const content =
+          directory === 'assets'
+            ? Buffer.alloc(options.supportFileSize, index)
+            : 'x'.repeat(options.supportFileSize)
+        writeFile(
+          join(skillDir, directory, `support-${index}.${extension}`),
+          content,
+        )
+      }
+    }
+  }
+
+  return { root, runner: createCliRunner({ cwd: root }) }
+}
+
+function defineScenario(name: string, options: FixtureOptions): void {
+  const consoleSilencer = createConsoleSilencer()
+  let fixture: LockfileFixture | null = null
+
+  async function setup(): Promise<void> {
+    if (fixture) return
+
+    consoleSilencer.silence()
+    fixture = createFixture(name, options)
+    await fixture.runner.setup()
+    await fixture.runner.run(['skills', 'approve', '--all', '--yes'])
+    if (options.changedSkill) {
+      writeFile(
+        join(
+          fixture.root,
+          'node_modules',
+          '@bench',
+          'lock-0',
+          'skills',
+          'skill-0',
+          'SKILL.md',
+        ),
+        '---\nname: skill-0\ndescription: changed benchmark skill\n---\n\nChanged.\n',
+      )
+    }
+  }
+
+  function teardown(): void {
+    if (fixture) {
+      fixture.runner.teardown()
+      rmSync(fixture.root, { recursive: true, force: true })
+      fixture = null
+    }
+    consoleSilencer.restore()
+  }
+
+  describe(`intent skills scan --json (${name})`, () => {
+    beforeAll(setup)
+    afterAll(teardown)
+
+    bench(
+      'scans lockfile state',
+      async () => {
+        if (!fixture) throw new Error('Lockfile fixture was not initialized')
+        await fixture.runner.run(['skills', 'scan', '--json'])
+      },
+      createBenchOptions(setup, teardown),
+    )
+  })
+}
+
+defineScenario('clean-eight-packages', {
+  packageCount: 8,
+  skillCount: 3,
+  supportFileCount: 3,
+  supportFileSize: 1024,
+})
+
+defineScenario('changed-skill', {
+  changedSkill: true,
+  packageCount: 8,
+  skillCount: 3,
+  supportFileCount: 3,
+  supportFileSize: 1024,
+})
+
+defineScenario('large-support-set', {
+  packageCount: 24,
+  skillCount: 4,
+  supportFileCount: 6,
+  supportFileSize: 8 * 1024,
+})

docs/cli/intent-list.md

@@ -117,7 +117,9 @@ The list as a whole has three special forms:
 - **Empty** (`"skills": []`): no package is surfaced, with an info notice printed to stderr.
 - **Wildcard** (`"skills": ["*"]`): every discovered package is surfaced, with an acknowledged-risk notice printed to stderr.
 
-A package that ships skills but is not listed is dropped. When packages are dropped this way, Intent prints one summary line naming them so you can opt in. In agent sessions, hidden sources are reported by count only; run `intent list --show-hidden` outside the agent session to review candidates. A listed package that was not discovered is reported as well. Matching is currently by package name. See [Configuration](../concepts/configuration) and [Trust model](../concepts/trust-model).
+A package that ships skills but is not listed is dropped. Human-facing output includes bounded dependency provenance when available, otherwise `provenance unknown`. In agent sessions, hidden sources are reported by count only; run `intent list --show-hidden` outside the agent session to review candidates. A listed package that was not discovered is reported as well. Matching uses `(kind, id)`. See [Configuration](../concepts/configuration) and [Trust model](../concepts/trust-model).
+
+When an npm and workspace source share a name and the requested skill, `intent load` rejects the unqualified use as ambiguous.
 
 ## Excludes
 
@@ -133,7 +135,7 @@ Manage persistent excludes with `intent exclude add|remove|list`.
 }
 ```
 
-A pattern without `#` excludes a whole package. A pattern with `#` excludes a single skill (`@scope/pkg#search-params`), and the skill segment may itself be a glob (`@scope/pkg#experimental-*`). A pattern may cross package boundaries at skill granularity (`*#experimental-*`). The `#*` shortcut (`@scope/pkg#*`) excludes the whole package. Only exact names and `*` wildcards are supported on each segment. Bare package-name patterns keep working unchanged.
+A pattern without `#` excludes a whole package. A pattern with `#` excludes a single skill (`@scope/pkg#search-params`), and the skill segment may itself be a glob (`@scope/pkg#experimental-*`). A pattern may cross package boundaries at skill granularity (`*#experimental-*`). The `#*` shortcut (`@scope/pkg#*`) excludes the whole package. Prefix a package segment with `npm:` or `workspace:` to target one source kind. Only exact names and `*` wildcards are supported on each segment. Bare package-name patterns keep working unchanged.
 
 An excluded package never triggers the unlisted-source warning, because an exclude is an explicit decision rather than an oversight.
 

docs/cli/intent-skills.md

@@ -0,0 +1,95 @@
+---
+title: intent skills
+id: intent-skills
+---
+
+`intent skills` manages `intent.lock`, the committed record of which skill-bearing sources you've approved and what their content looked like when you approved it. Four subcommands: `scan`, `diff` (read-only), `approve`, and `update` (mutating).
+
+```bash
+npx intent skills <scan|diff|approve|update> [source] [--json] [--all] [--yes] [--frozen] [--no-frozen]
+```
+
+See [Lockfile and frozen mode](../security/lockfile) for what `intent.lock` is and what frozen mode guarantees.
+
+## `intent skills scan`
+
+```bash
+npx intent skills scan [--json] [--frozen] [--no-frozen]
+```
+
+Read-only. Discovers current skill-bearing sources, computes each source's `contentHash`, and reports drift against `intent.lock`.
+
+- No lock found: prints `No intent.lock found. Run \`intent skills approve --all\` to create one.`
+- Lock is clean: prints `intent.lock is up to date.`
+- Lock is stale: prints `intent.lock is out of date: N added, N removed, N changed.`
+- Discovered sources not in `intent.skills`: names each source with bounded dependency provenance when available, falls back to `provenance unknown`, and points at `intent.skills`/`intent.exclude`. Agent-mode output remains count-only.
+- `--json` prints `{ frozen, hiddenSourceCount, hasLockfile, added, removed, changed, isClean }`
+
+## `intent skills diff`
+
+```bash
+npx intent skills diff [--json] [--frozen] [--no-frozen]
+```
+
+Read-only. Same underlying computation as `scan`, but change-focused: prints `Added:`/`Removed:`/`Changed:` sections with per-field diffs (`version`, `resolution`, `skills`, `contentHash`, `manifestHash`, `capabilities`). It then displays the complete current canonical text for every added or changed source. Binary files are summarized by path, byte length, and hash. Control and bidirectional characters are escaped in the line-numbered text display so package content cannot manipulate terminal output. Unchanged sources are omitted.
+
+```
+Changed:
+  ~ npm:@acme/query
+      version: "1.0.0" -> "1.1.0"
+      resolution: "npm:@acme/query@1.0.0" -> "npm:@acme/query@1.1.0"
+      contentHash: "sha256-492ac4..." -> "sha256-2631b3..."
+```
+
+## `intent skills approve [source]`
+
+```bash
+npx intent skills approve [source] [--all] [--yes]
+```
+
+Writes `intent.lock`. This is the trust decision. Before any prompt or non-interactive write, Intent displays the current canonical text and binary summaries for the affected sources. Removed sources display their locked skill paths and aggregate hash because the old file bytes are not stored in `intent.lock`.
+
+- **No arg, no `--all`/`--yes`:** interactive per-pending-change prompt (approve/skip each). Fails if stdin isn't a TTY.
+- **`--all` or `--yes`:** displays every pending change, then accepts them without prompting. This is the first-run path that creates the initial lock.
+- **A single source:** `approve npm:@tanstack/query`, `approve workspace:my-package`, or a bare name (`approve foo`) if it resolves unambiguously against currently-discovered sources. Two sources sharing a bare name across kinds (`npm:foo` and `workspace:foo`) error instead of guessing — pass `kind:id` explicitly.
+- Re-serializes the whole file deterministically: identical inputs produce a byte-identical `intent.lock`.
+- Only touches the targeted entry (single-source form) or all pending changes (`--all`/`--yes`) — never silently drops an entry you didn't act on.
+- Refuses in frozen mode (exit `5`).
+
+## `intent skills update [source]`
+
+```bash
+npx intent skills update [source] [--all] [--yes]
+```
+
+Writes `intent.lock`. It mechanically re-syncs version and resolution for matching **already-locked** entries. Changes to skills, content hashes, manifests, capabilities, declared secrets, or MCP metadata require `--yes`; before writing them, `update` displays the same current content review as `diff` and `approve`.
+
+- Only touches sources present in **both** the lock and the current scan. It never adds a newly-discovered source (that's `approve`'s job) and never drops a source that's no longer discovered (also `approve`'s job — removing a source from the trust boundary is itself a trust decision).
+- Reports pending added/removed drift it didn't touch: `N added, M removed source(s) still pending. Run \`intent skills approve\` to review.`
+- Makes zero network calls and zero subprocess calls — it only reads what's already on disk.
+- Refuses in frozen mode (exit `5`).
+
+## Options
+
+- `--json`: with `scan`/`diff`, print the structured diff instead of text
+- `--all`: with `approve`/`update`, act on all pending changes without prompting
+- `--yes`: with `approve`, accept all pending changes non-interactively; with `update`, accept reviewed trust-bearing changes
+- `--frozen`: force frozen mode, regardless of `INTENT_FROZEN`/`CI` auto-detection
+- `--no-frozen`: force interactive mode — overrides `INTENT_FROZEN` and the `CI` auto-detect (highest-precedence explicit override)
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | ok |
+| `1` | generic CLI usage or parse error |
+| `2` | drift found under frozen mode |
+| `3` | unapproved/unlisted skill-bearing source found under frozen mode |
+| `4` | no `intent.lock` found under frozen mode |
+| `5` | `approve`/`update` refused because frozen mode disallows mutation |
+| `6` | `intent.lock` is malformed or from an unsupported (newer) `lockfileVersion` |
+
+## Related
+
+- [Lockfile and frozen mode](../security/lockfile)
+- [Trust model](../concepts/trust-model)

docs/concepts/configuration.md

@@ -30,7 +30,9 @@ Each array entry names one source:
 | `workspace:@scope/pkg` | workspace | A package in the current workspace. |
 | `git:<host>/<repo>#<ref>` | git | Reserved. Not yet supported, and rejected until a future version adds it. |
 
-A malformed entry fails the whole command, and every bad entry is reported at once. Intent currently matches an allowlist entry against a discovered package by name. This matching will tighten in a future version.
+A malformed entry fails the whole command, and every bad entry is reported at once. Intent matches a source by `(kind, id)`: `workspace:foo` never authorizes an npm-installed `foo`.
+
+If both `npm:foo` and `workspace:foo` provide the same requested skill, `intent load foo#skill` fails as ambiguous instead of selecting one source by discovery order. Narrow the allowlist to one source before loading it.
 
 ### Special forms
 
@@ -40,7 +42,7 @@ The list as a whole has three special forms:
 - **Empty.** `"skills": []`. No package is surfaced. Intent prints an info notice to stderr.
 - **Wildcard.** `"skills": ["*"]`. Every discovered package is surfaced. Intent prints an acknowledged-risk notice to stderr, since unvetted skills may reach your agent.
 
-A package that ships skills but is not listed is dropped. When packages are dropped this way, Intent prints one summary line naming them so you can opt in. A listed package that was not discovered is reported as well.
+A package that ships skills but is not listed is dropped. Human-facing output includes bounded dependency provenance when available, otherwise `provenance unknown`. A listed package that was not discovered is reported as well.
 
 ### Existing projects
 
@@ -85,4 +87,6 @@ Pattern grammar:
 - A pattern may cross package boundaries at skill granularity: `*#experimental-*`.
 - The `#*` shortcut excludes the whole package: `@scope/pkg#*`.
 
+Prefix a package segment with `npm:` or `workspace:` to target one source kind, for example `workspace:foo` or `npm:foo#experimental-*`. Bare package patterns remain broad and match either kind.
+
 Only exact names and `*` wildcards are supported on each segment. Bare package-name patterns keep working unchanged. An excluded package does not trigger the unlisted-source warning, because an exclude is an explicit decision.

docs/concepts/trust-model.md

@@ -21,8 +21,10 @@ Intent reads package data as files. It never imports, requires, or executes the
 
 One exception is sanctioned: in Yarn Plug'n'Play projects, Intent loads Yarn's PnP runtime (`.pnp.cjs`) to map package identities to readable locations. It loads no package entry points, bins, lifecycle scripts, or other package-provided JavaScript. An ESLint rule enforces this invariant in the discovery code.
 
-## What the allowlist does not cover yet
+## Source identity and remaining limits
 
-Matching is currently by package name. A `workspace:foo` entry and a bare `foo` entry both authorize a discovered package named `foo`, because the scanner does not yet distinguish a workspace member from a published package of the same name. This errs toward permitting a same-named package, never toward denying one you listed. A future version tightens matching once the scanner carries that signal.
+Intent matches allowlist entries by `(kind, id)`. `workspace:foo` authorizes only the workspace member named `foo`; it does not authorize an installed `npm:foo`. A bare `foo` entry is normalized to the npm source kind. Same-named workspace and npm packages remain distinct sources throughout discovery, locking, and approval.
+
+Source trust and content approval remain separate decisions. When `intent.lock` exists, ordinary skill loading and agent catalog generation reject installed content that differs from the approved hashes. A missing lockfile does not silently approve anything; outside frozen mode it preserves the bootstrap path until the user reviews content with `intent skills diff` and writes the first lock with `intent skills approve`.
 
 The `git:` source kind is reserved. Intent parses and validates the shape, then rejects it until a future version can pin the resolved ref and content hash. A git entry never loads silently.

docs/config.json

@@ -37,6 +37,10 @@
         {
           "label": "Configuration",
           "to": "concepts/configuration"
+        },
+        {
+          "label": "Lockfile and frozen mode",
+          "to": "security/lockfile"
         }
       ]
     },
@@ -82,6 +86,10 @@
         {
           "label": "intent stale",
           "to": "cli/intent-stale"
+        },
+        {
+          "label": "intent skills",
+          "to": "cli/intent-skills"
         }
       ]
     }