@thecat69/cache-ctrl 1.0.0

package/skills/cache-ctrl-local/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: cache-ctrl-local
+description: How to use cache-ctrl to detect file changes and manage the local context cache
+---
+
+# cache-ctrl — Local Cache Usage
+
+Manage `.ai/local-context-gatherer_cache/context.json` to avoid redundant full-repo scans.
+Three tiers of access — use the best one available.
+
+## Availability Detection (run once at startup)
+
+1. Call `cache_ctrl_check_files` (built-in tool).
+   - Success → **use Tier 1** for all operations below.
+   - Failure (tool not found / permission denied) → continue to step 2.
+2. Run `bash: "which cache-ctrl"`.
+   - Exit 0 → **use Tier 2** for all operations below.
+   - Not found → **use Tier 3** for all operations below.
+
+---
+
+## Fact-Writing Rules
+
+Facts must be **concise observations** about a file — not reproductions of its content.
+
+- **Each fact string must be ≤ 300 characters** (schema hard limit: 800). If an observation needs more, split it into two facts or summarize.
+- **Max 30 facts per file.** Choose only the most architecturally meaningful observations.
+- **Never write**: raw import lines, function bodies, code snippets, or verbatim text from the file.
+- **Do write**: what the file exports, what pattern it uses, what dependencies it has, what its responsibility is.
+
+**Good fact** ✅:
+> `"Exports writeCommand — validates subject, merges per-path facts atomically, returns Result<WriteResult>"`
+
+**Bad fact** ❌:
+> `"import { ExternalCacheFileSchema, LocalCacheFileSchema } from '../types/cache.js'; import { ErrorCode, Result } from '../types/result.js'; import { WriteArgs, WriteResult } from '../types/commands.js'"` ← this is raw file content
+
+**Global facts** are for cross-cutting structural observations only (e.g. CLI entry pattern, installation steps). Max 20, each ≤ 300 chars. Only update global_facts when you re-read a structural file (AGENTS.md, install.sh, package.json, *.toml, opencode.json).
+
+---
+
+## Mandatory: Write Before Return
+
+**Every invocation must call `cache_ctrl_write` before returning.** Returning without writing is a failure — the orchestrator will detect the missing write and re-invoke you.
+
+Sequential checklist (do not skip any step):
+
+1. Call `cache_ctrl_check_files` — identify changed/new files
+2. Read only the changed/new files (skip unchanged ones)
+3. Extract concise facts per file (follow Fact-Writing Rules above)
+4. **Call `cache_ctrl_write` — MANDATORY** (even if only 1 file changed, even if only global_facts changed)
+5. Return your summary
+
+If there are no changed files, the cache already exists and is non-empty, **and you were not invoked after a cache invalidation**, you may skip the write — but only in this case.
+
+---
+
+## Startup Workflow
+
+### 1. Check if tracked files changed
+
+**Tier 1:** Call `cache_ctrl_check_files` (no parameters).
+**Tier 2:** `cache-ctrl check-files`
+**Tier 3:** `read` `.ai/local-context-gatherer_cache/context.json`.
+  - File absent → cold start, proceed to scan.
+  - File present → check `timestamp`. If older than 1 hour, treat as stale and re-scan. Otherwise treat as fresh.
+
+Result interpretation (Tier 1 & 2):
+- `status: "unchanged"` → tracked files are content-stable; skip re-scan and return cached context.
+- `status: "changed"` → at least one tracked file changed; proceed to **delta scan** (read content of `changed_files` + `new_files` only — do not re-read unchanged files).
+- `status: "unchanged"` with empty `tracked_files` → cold start, proceed to scan.
+
+The response also reports:
+- `new_files` — untracked non-ignored files absent from cache, plus git-tracked files absent from cache when the cache is non-empty (blank-slate caches skip git-tracked files to avoid false positives on cold start)
+- `deleted_git_files` — git-tracked files deleted from the working tree (reported by `git ls-files --deleted`)
+
+> **⚠ Cache is non-exhaustive**: `status: "unchanged"` only confirms that previously-tracked files are content-stable — it does not mean the file set is complete. Always check `new_files` and `deleted_git_files` in the response; if either is non-empty, include those paths in the next write to keep the cache up to date.
+
+### 2. Invalidate before writing (optional)
+
+> Do this only if cache is really outdated and a full rescan is needed. Otherwise just proceed with next step (writing).
+
+**Tier 1:** Call `cache_ctrl_invalidate` with `agent: "local"`.
+**Tier 2:** `cache-ctrl invalidate local`
+**Tier 3:** Skip — overwriting the file in step 3 is sufficient.
+
+### 3. Write cache after scanning
+
+**Always use the write tool/command — never edit the file directly.** Direct writes bypass schema validation and can silently corrupt the cache format.
+
+> **Write is per-path merge**: Submitted `tracked_files` entries replace existing entries for the same paths. Paths not in the submission are preserved. Entries for files deleted from disk are evicted automatically (no agent action needed).
+
+#### Input fields (`content` object)
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `topic` | `string` | ✅ | Human description of what was scanned |
+| `description` | `string` | ✅ | One-liner for keyword search |
+| `tracked_files` | `Array<{ path: string }>` | ✅ | Paths to track; `mtime` and `hash` are auto-computed by the tool |
+| `global_facts` | `string[]` | optional | Repo-level facts; last-write-wins; see trigger rule below |
+| `facts` | `Record<string, string[]>` | optional | Per-file facts keyed by path; per-path merge |
+| `cache_miss_reason` | `string` | optional | Why the previous cache was discarded |
+
+> **Cold start vs incremental**: On first run (no existing cache), submit all relevant files. On subsequent runs, submit only new and changed files — the tool merges them in.
+
+> **Auto-set by the tool — do not include**: `timestamp` (current UTC), `mtime` (filesystem `lstat()`), and `hash` (SHA-256) per `tracked_files` entry.
+
+### Scope rule for `facts`
+
+Submit `facts` ONLY for files you actually read in this session (i.e., files present in
+your submitted `tracked_files`). Never reconstruct or re-submit facts for unchanged files —
+the tool preserves them automatically via per-path merge.
+
+Submitting a facts key for a path absent from submitted `tracked_files` is a
+VALIDATION_ERROR and the entire write is rejected.
+
+### Fact completeness
+
+When a file appears in `changed_files` or `new_files`, read the **whole file** before writing
+facts — not just the diff. A 2-line change does not support a complete re-description of the
+file, and submitting partial facts for a re-read path **permanently replaces** whatever was
+cached before.
+
+Write facts as **enumerable observations** — one entry per notable characteristic (purpose,
+structure, key dependencies, patterns, constraints, entry points). Do not bundle multiple
+distinct properties into a single string. A file should have as many fact entries as it has
+distinct notable properties, not a prose summary compressed into one or two lines.
+
+### When to submit `global_facts`
+
+Submit `global_facts` only when you re-read at least one structural file in this session:
+AGENTS.md, install.sh, opencode.json, package.json, *.toml config files.
+
+If none of those are in `changed_files` or `new_files`, omit `global_facts` from the write.
+The existing value is preserved automatically.
+
+### Eviction
+
+Facts for files deleted from disk are evicted automatically on the next write — no agent
+action needed. `global_facts` is never evicted.
+
+#### Tier 1 — `cache_ctrl_write`
+
+```json
+{
+  "agent": "local",
+  "content": {
+    "topic": "neovim plugin configuration scan",
+    "description": "Full scan of lua/plugins tree for neovim lazy.nvim setup",
+    "tracked_files": [
+      { "path": "lua/plugins/ui/bufferline.lua" },
+      { "path": "lua/plugins/lsp/nvim-lspconfig.lua" }
+    ]
+  }
+}
+```
+
+#### Tier 2 — CLI
+
+`cache-ctrl write local --data '<json>'` — pass the same `content` object as JSON string.
+
+#### Tier 3
+
+Not available — there is no direct-file fallback for writes. If neither Tier 1 nor Tier 2 is accessible, request access to one of them.
+
+### 4. Confirm cache (optional)
+
+**Tier 1:** Call `cache_ctrl_list` with `agent: "local"` to confirm the entry was written.
+**Tier 2:** `cache-ctrl list --agent local`
+**Tier 3:** `read` `.ai/local-context-gatherer_cache/context.json` and verify `timestamp` is current.
+
+Note: local entries show `is_stale: true` only when `cache_ctrl_check_files` detects actual changes (changed files, new non-ignored files, or deleted files). A freshly-written cache with no subsequent file changes will show `is_stale: false`.
+
+---
+
+## Tool / Command Reference
+
+| Operation | Tier 1 (built-in) | Tier 2 (CLI) | Tier 3 (manual) |
+|---|---|---|---|
+| Detect file changes | `cache_ctrl_check_files` | `cache-ctrl check-files` | read `context.json`, check `timestamp` |
+| Invalidate cache | `cache_ctrl_invalidate` | `cache-ctrl invalidate local` | overwrite file in next step |
+| Confirm written | `cache_ctrl_list` | `cache-ctrl list --agent local` | `read` file, check `timestamp` |
+| Read facts (filtered) | `cache_ctrl_inspect` with `filter`, `folder`, or `searchFacts` | `cache-ctrl inspect local context --filter <kw>[,<kw>...]` / `--folder <path>` / `--search-facts <kw>[,<kw>...]` | `read` file, extract `facts`/`global_facts` |
+| Read all facts (rare) | `cache_ctrl_inspect` (no filter) | `cache-ctrl inspect local context` | `read` file directly |
+| Write cache | `cache_ctrl_write` | `cache-ctrl write local --data '<json>'` | ❌ not available |
+
+> **⚠ Always use at least one filter when reading facts for a specific task.** Three targeting options are available — use the most specific one that fits your task:
+>
+> | Flag | What it matches | Best for |
+> |---|---|---|
+> | `--filter <kw>` | File path contains keyword | When you know which files by name/path segment |
+> | `--folder <path>` | File path starts with folder prefix (recursive) | When you need all files in a directory subtree |
+> | `--search-facts <kw>` | Any fact string contains keyword | When you need files related to a concept, pattern, or API |
+>
+> The flags are AND-ed when combined. Omit all filters only when you genuinely need facts for the entire repository (rare — e.g. building a full index; only appropriate for ≤ ~20 tracked files). An unfiltered `inspect` on a large repo can return thousands of fact strings.
+
+> **`tracked_files` is never returned by `inspect` for the local agent.** It is internal operational metadata consumed by `check-files`. It will not appear in any inspect response.
+
+## server_time in Responses
+
+Every `cache_ctrl_*` tool call returns a `server_time` field at the outer JSON level:
+
+```json
+{ "ok": true, "value": { ... }, "server_time": "2026-04-05T12:34:56.789Z" }
+```
+
+Use this to assess how stale stored timestamps are — you do not need `bash` or system access to know the current time.
+
+## Cache Location
+
+`.ai/local-context-gatherer_cache/context.json` — single file, no per-subject splitting.
+
+No time-based TTL for Tier 1/2. Freshness determined by `cache_ctrl_check_files`.
+Tier 3 uses a 1-hour `timestamp` TTL as a rough proxy.

package/src/cache/cacheManager.ts

@@ -0,0 +1,241 @@
+import { readFile, writeFile, rename, stat, unlink, readdir, mkdir } from "node:fs/promises";
+import { open } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import type { AgentType, CacheEntry, ExternalCacheFile, LocalCacheFile } from "../types/cache.js";
+import { ExternalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { getFileStem } from "../utils/fileStem.js";
+
+const LOCK_RETRY_INTERVAL_MS = 50;
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_STALE_AGE_MS = 30_000;
+
+export async function findRepoRoot(startDir: string): Promise<string> {
+  let current = startDir;
+  while (true) {
+    try {
+      await stat(join(current, ".git"));
+      return current;
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) {
+        // Reached filesystem root — fall back to startDir
+        return startDir;
+      }
+      current = parent;
+    }
+  }
+}
+
+export function resolveCacheDir(agent: AgentType, repoRoot: string): string {
+  if (agent === "external") {
+    return join(repoRoot, ".ai", "external-context-gatherer_cache");
+  }
+  return join(repoRoot, ".ai", "local-context-gatherer_cache");
+}
+
+export async function readCache(filePath: string): Promise<Result<Record<string, unknown>>> {
+  try {
+    const content = await readFile(filePath, "utf-8");
+    try {
+      const parsed = JSON.parse(content) as Record<string, unknown>;
+      return { ok: true, value: parsed };
+    } catch {
+      return { ok: false, error: `Failed to parse JSON: ${filePath}`, code: ErrorCode.PARSE_ERROR };
+    }
+  } catch (err) {
+    const error = err as NodeJS.ErrnoException;
+    if (error.code === "ENOENT") {
+      return { ok: false, error: `Cache file not found: ${filePath}`, code: ErrorCode.FILE_NOT_FOUND };
+    }
+    return { ok: false, error: `Failed to read file: ${filePath}: ${error.message}`, code: ErrorCode.FILE_READ_ERROR };
+  }
+}
+
+export async function writeCache(
+  filePath: string,
+  updates: Partial<ExternalCacheFile> | Partial<LocalCacheFile> | Record<string, unknown>,
+  mode: "merge" | "replace" = "merge",
+): Promise<Result<void>> {
+  // Ensure parent directory exists before acquiring the lock
+  await mkdir(dirname(filePath), { recursive: true });
+
+  const lockResult = await acquireLock(filePath);
+  if (!lockResult.ok) return lockResult;
+
+  try {
+    let merged: Record<string, unknown>;
+
+    if (mode === "replace") {
+      merged = updates as Record<string, unknown>;
+    } else {
+      // Read existing content if file exists
+      let existing: Record<string, unknown> = {};
+      const readResult = await readCache(filePath);
+      if (readResult.ok) {
+        existing = readResult.value;
+      } else if (readResult.code !== ErrorCode.FILE_NOT_FOUND) {
+        return { ok: false, error: readResult.error, code: readResult.code };
+      }
+      merged = { ...existing, ...updates };
+    }
+    const tmpPath = `${filePath}.tmp.${process.pid}.${randomBytes(6).toString("hex")}`;
+
+    try {
+      await writeFile(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
+      await rename(tmpPath, filePath);
+      return { ok: true, value: undefined };
+    } catch (err) {
+      const error = err as NodeJS.ErrnoException;
+      // Clean up tmp file on failure
+      try {
+        await unlink(tmpPath);
+      } catch {
+        // Ignore cleanup failure
+      }
+      return { ok: false, error: `Failed to write cache: ${error.message}`, code: ErrorCode.FILE_WRITE_ERROR };
+    }
+  } finally {
+    await releaseLock(filePath);
+  }
+}
+
+export async function listCacheFiles(agent: AgentType, repoRoot: string): Promise<Result<string[]>> {
+  const cacheDir = resolveCacheDir(agent, repoRoot);
+  try {
+    const entries = await readdir(cacheDir);
+    const jsonFiles = entries
+      .filter((name) => name.endsWith(".json") && !name.endsWith(".lock"))
+      .map((name) => join(cacheDir, name));
+    return { ok: true, value: jsonFiles };
+  } catch (err) {
+    const error = err as NodeJS.ErrnoException;
+    if (error.code === "ENOENT") {
+      return { ok: true, value: [] };
+    }
+    return { ok: false, error: `Failed to list cache directory: ${error.message}`, code: ErrorCode.FILE_READ_ERROR };
+  }
+}
+
+/**
+ * Loads all valid external cache entries for a repo, returning a `CacheEntry` array.
+ * Files that cannot be read or fail schema validation are skipped with a warning to stderr.
+ * Returns `ok: false` only when the cache directory itself cannot be listed.
+ */
+export async function loadExternalCacheEntries(repoRoot: string): Promise<Result<CacheEntry[]>> {
+  const filesResult = await listCacheFiles("external", repoRoot);
+  if (!filesResult.ok) return filesResult;
+
+  const entries: CacheEntry[] = [];
+  for (const filePath of filesResult.value) {
+    const readResult = await readCache(filePath);
+    if (!readResult.ok) {
+      process.stderr.write(`[cache-ctrl] Warning: skipping invalid JSON file: ${filePath}\n`);
+      continue;
+    }
+    const parseResult = ExternalCacheFileSchema.safeParse(readResult.value);
+    if (!parseResult.success) {
+      process.stderr.write(`[cache-ctrl] Warning: skipping malformed external cache file: ${filePath}\n`);
+      continue;
+    }
+    const data: ExternalCacheFile = parseResult.data;
+    const stem = getFileStem(filePath);
+    const subject = data.subject ?? stem;
+    if (subject !== stem) {
+      process.stderr.write(`[cache-ctrl] Warning: subject "${subject}" does not match file stem "${stem}" in ${filePath}\n`);
+    }
+    entries.push({
+      file: filePath,
+      agent: "external",
+      subject,
+      description: data.description,
+      fetched_at: data.fetched_at ?? "",
+    });
+  }
+
+  return { ok: true, value: entries };
+}
+
+export async function acquireLock(filePath: string): Promise<Result<void>> {
+  const lockPath = `${filePath}.lock`;
+  const start = Date.now();
+
+  while (true) {
+    try {
+      // O_EXCL: atomic create, fails if exists
+      const fh = await open(lockPath, "wx");
+      await fh.write(`${process.pid}\n`);
+      await fh.close();
+      return { ok: true, value: undefined };
+    } catch (err) {
+      const error = err as NodeJS.ErrnoException;
+      if (error.code !== "EEXIST") {
+        return { ok: false, error: `Lock error: ${error.message}`, code: ErrorCode.LOCK_ERROR };
+      }
+
+      // Lock exists — check if stale
+      const staleResult = await isLockStale(lockPath);
+      if (staleResult) {
+        // Remove stale lock and retry immediately
+        try {
+          await unlink(lockPath);
+        } catch {
+          // Another process may have removed it already
+        }
+        continue;
+      }
+
+      // Check timeout
+      if (Date.now() - start >= LOCK_TIMEOUT_MS) {
+        return { ok: false, error: "Lock timeout: could not acquire lock within 5 seconds", code: ErrorCode.LOCK_TIMEOUT };
+      }
+
+      // Wait and retry
+      await sleep(LOCK_RETRY_INTERVAL_MS);
+    }
+  }
+}
+
+export async function releaseLock(filePath: string): Promise<void> {
+  const lockPath = `${filePath}.lock`;
+  try {
+    await unlink(lockPath);
+  } catch (err) {
+    const error = err as NodeJS.ErrnoException;
+    if (error.code !== "ENOENT") {
+      console.warn(`[cache-ctrl] Warning: failed to release lock ${lockPath}: ${error.message}`);
+    }
+  }
+}
+
+async function isLockStale(lockPath: string): Promise<boolean> {
+  try {
+    const lockStat = await stat(lockPath);
+    const ageMs = Date.now() - lockStat.mtimeMs;
+    if (ageMs > LOCK_STALE_AGE_MS) {
+      return true;
+    }
+
+    const content = await readFile(lockPath, "utf-8");
+    const pidStr = content.trim();
+    const pid = parseInt(pidStr, 10);
+    if (isNaN(pid) || pid <= 0 || pid >= 4_194_304) {
+      return true;
+    }
+
+    try {
+      process.kill(pid, 0);
+      return false; // PID is alive
+    } catch {
+      return true; // PID is dead
+    }
+  } catch {
+    // Cannot read lock — treat as stale
+    return true;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/cache/externalCache.ts

@@ -0,0 +1,127 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExternalCacheFile, CacheEntry } from "../types/cache.js";
+import { ExternalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import { readCache, listCacheFiles } from "./cacheManager.js";
+import { scoreEntry } from "../search/keywordSearch.js";
+import { getFileStem } from "../utils/fileStem.js";
+
+const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+export function resolveExternalCacheDir(repoRoot: string): string {
+  return join(repoRoot, ".ai", "external-context-gatherer_cache");
+}
+
+export async function resolveExternalFiles(repoRoot: string): Promise<Result<string[]>> {
+  const cacheDir = resolveExternalCacheDir(repoRoot);
+  try {
+    const entries = await readdir(cacheDir);
+    return {
+      ok: true,
+      value: entries
+        .filter((name) => name.endsWith(".json") && !name.endsWith(".lock"))
+        .map((name) => join(cacheDir, name)),
+    };
+  } catch (err) {
+    const error = err as NodeJS.ErrnoException;
+    if (error.code === "ENOENT") {
+      return { ok: true, value: [] };
+    }
+    return { ok: false, error: `Failed to list external cache directory: ${error.message}`, code: ErrorCode.FILE_READ_ERROR };
+  }
+}
+
+export function isExternalStale(entry: ExternalCacheFile, maxAgeMs?: number): boolean {
+  if (!entry.fetched_at) return true;
+  const threshold = maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+  const age = Date.now() - new Date(entry.fetched_at).getTime();
+  return age > threshold;
+}
+
+export interface HeaderMeta {
+  etag?: string;
+  last_modified?: string;
+  checked_at: string;
+  status: "fresh" | "stale" | "unchecked";
+}
+
+export function mergeHeaderMetadata(
+  existing: ExternalCacheFile,
+  updates: Record<string, HeaderMeta>,
+): ExternalCacheFile {
+  return {
+    ...existing,
+    header_metadata: {
+      ...existing.header_metadata,
+      ...updates,
+    },
+  };
+}
+
+export function getAgeHuman(fetchedAt: string): string {
+  if (!fetchedAt) return "invalidated";
+
+  const now = Date.now();
+  const fetched = new Date(fetchedAt).getTime();
+  const diffMs = now - fetched;
+
+  if (diffMs < 0) return "just now";
+
+  const minutes = Math.floor(diffMs / 60_000);
+  const hours = Math.floor(diffMs / 3_600_000);
+  const days = Math.floor(diffMs / 86_400_000);
+
+  if (days >= 1) {
+    return days === 1 ? "1 day ago" : `${days} days ago`;
+  }
+  if (hours >= 1) {
+    return hours === 1 ? "1 hour ago" : `${hours} hours ago`;
+  }
+  if (minutes >= 1) {
+    return minutes === 1 ? "1 minute ago" : `${minutes} minutes ago`;
+  }
+  return "just now";
+}
+
+/**
+ * Resolves the file path of the best-scoring external cache entry for a given subject keyword.
+ * Returns NO_MATCH if no entry scores above zero.
+ */
+export async function resolveTopExternalMatch(repoRoot: string, subject: string): Promise<Result<string>> {
+  const filesResult = await listCacheFiles("external", repoRoot);
+  if (!filesResult.ok) return filesResult;
+
+  const candidates: Array<{ filePath: string; entry: CacheEntry }> = [];
+  for (const filePath of filesResult.value) {
+    const readResult = await readCache(filePath);
+    if (!readResult.ok) continue;
+    const parseResult = ExternalCacheFileSchema.safeParse(readResult.value);
+    if (!parseResult.success) continue;
+    const data = parseResult.data;
+    const stem = getFileStem(filePath);
+    const entrySubject = data.subject ?? stem;
+    candidates.push({
+      filePath,
+      entry: {
+        file: filePath,
+        agent: "external",
+        subject: entrySubject,
+        description: data.description,
+        fetched_at: data.fetched_at ?? "",
+      },
+    });
+  }
+
+  const keywords = [subject];
+  const scored = candidates
+    .map((c) => ({ ...c, score: scoreEntry(c.entry, keywords) }))
+    .filter((c) => c.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  if (scored.length === 0) {
+    return { ok: false, error: `No cache entry matched keyword "${subject}"`, code: ErrorCode.NO_MATCH };
+  }
+
+  return { ok: true, value: scored[0]!.filePath };
+}

package/src/cache/localCache.ts

@@ -0,0 +1,9 @@
+import { join } from "node:path";
+
+export function resolveLocalCacheDir(repoRoot: string): string {
+  return join(repoRoot, ".ai", "local-context-gatherer_cache");
+}
+
+export function resolveLocalCachePath(repoRoot: string): string {
+  return join(resolveLocalCacheDir(repoRoot), "context.json");
+}

package/src/commands/checkFiles.ts

@@ -0,0 +1,83 @@
+import { isAbsolute, posix, relative, sep } from "node:path";
+import { findRepoRoot, readCache } from "../cache/cacheManager.js";
+import { resolveLocalCachePath } from "../cache/localCache.js";
+import { compareTrackedFile } from "../files/changeDetector.js";
+import { getGitTrackedFiles, getGitDeletedFiles, getUntrackedNonIgnoredFiles } from "../files/gitFiles.js";
+import { LocalCacheFileSchema } from "../types/cache.js";
+import { ErrorCode, type Result } from "../types/result.js";
+import type { CheckFilesResult } from "../types/commands.js";
+
+const toPosix = (p: string) => p.split(sep).join(posix.sep);
+
+export async function checkFilesCommand(): Promise<Result<CheckFilesResult["value"]>> {
+  try {
+    const repoRoot = await findRepoRoot(process.cwd());
+    const localPath = resolveLocalCachePath(repoRoot);
+
+    const readResult = await readCache(localPath);
+    if (!readResult.ok) return readResult;
+
+    const parseResult = LocalCacheFileSchema.safeParse(readResult.value);
+    if (!parseResult.success) {
+      return { ok: false, error: `Malformed local cache file: ${localPath}`, code: ErrorCode.PARSE_ERROR };
+    }
+    const data = parseResult.data;
+    const trackedFiles = data.tracked_files;
+
+    const changedFiles: Array<{ path: string; reason: "mtime" | "hash" | "missing" }> = [];
+    const unchangedFiles: string[] = [];
+    const missingFiles: string[] = [];
+
+    for (const trackedFile of trackedFiles) {
+      const result = await compareTrackedFile(trackedFile, repoRoot);
+      if (result.status === "unchanged") {
+        unchangedFiles.push(trackedFile.path);
+      } else if (result.status === "missing") {
+        missingFiles.push(trackedFile.path);
+        changedFiles.push({ path: trackedFile.path, reason: "missing" });
+      } else {
+        changedFiles.push({ path: trackedFile.path, reason: result.reason ?? "mtime" });
+      }
+    }
+
+    const [gitTrackedFiles, deletedGitFiles, untrackedNonIgnoredFiles] = await Promise.all([
+      getGitTrackedFiles(repoRoot),
+      getGitDeletedFiles(repoRoot),
+      getUntrackedNonIgnoredFiles(repoRoot),
+    ]);
+    const toRepoRelativePosix = (filePath: string): string => {
+      const rel = isAbsolute(filePath) ? relative(repoRoot, filePath) : filePath;
+      return rel.split(sep).join(posix.sep);
+    };
+    const cachedPaths = new Set(trackedFiles.map((f) => toRepoRelativePosix(f.path)));
+    // When tracked_files is empty (blank-slate), skip git-tracked files from new_files
+    // because those were already present before this cache was written.
+    // Untracked non-ignored files are always reported as new — they represent newly
+    // created files that the user added to the working tree.
+    const baseFiles = trackedFiles.length > 0 ? gitTrackedFiles : [];
+    const newFiles = [...new Set([...baseFiles, ...untrackedNonIgnoredFiles])].filter(
+      (p) => !cachedPaths.has(toRepoRelativePosix(p)),
+    );
+
+    return {
+      ok: true,
+      value: {
+        status:
+          changedFiles.length > 0 ||
+          missingFiles.length > 0 ||
+          newFiles.length > 0 ||
+          deletedGitFiles.length > 0
+            ? "changed"
+            : "unchanged",
+        changed_files: changedFiles,
+        unchanged_files: unchangedFiles,
+        missing_files: missingFiles,
+        new_files: newFiles,
+        deleted_git_files: deletedGitFiles,
+      },
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: msg, code: ErrorCode.UNKNOWN };
+  }
+}