vericontext 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vericontext contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,268 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./assets/logo-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="./assets/logo-light.png">
+    <img alt="vericontext" src="./assets/logo-light.png" width="360">
+  </picture>
+</p>
+
+<h3 align="center">Docs lie. Hashes don't.</h3>
+
+<p align="center">
+  Deterministic, hash-based verification for docs that reference code.<br>
+  Fail-closed. Zero fuzzy matching. One stale citation → entire doc fails.
+</p>
+
+<!-- BADGES:START -->
+<!-- generated by add-badges 2026-02-23 -->
+<p align="center">
+  <a href="https://www.npmjs.com/package/vericontext"><img src="https://img.shields.io/npm/v/vericontext?style=flat-square&logo=npm&logoColor=white" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License: MIT"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square" alt="MCP compatible"></a>
+  <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node >= 20"></a>
+</p>
+<!-- BADGES:END -->
+
+<p align="center">
+  <b>English</b> ·
+  <a href="README-ko.md">한국어</a>
+</p>
+
+<p align="center">
+  <a href="#the-problem">Why</a> ·
+  <a href="#setup">Setup</a> ·
+  <a href="#github-actions">CI</a> ·
+  <a href="#how-it-works">How It Works</a> ·
+  <a href="#cli-reference">CLI</a>
+</p>
+
+---
+
+## The Problem
+
+AI coding agents now scatter `README.md` and `AGENTS.md` across every directory — `deep init` style. It works great until the code changes and the docs don't. Files move, functions get rewritten, but the docs still say *"this logic lives in `src/handler.ts` at L30-L45."*
+
+Over time, **your docs become liars.** And agents that trust those docs make worse decisions.
+
+VeriContext embeds a **SHA-256 content hash** into every code citation at write time. When you verify later, either the hash matches or it doesn't. No fuzzy recovery. No "close enough."
+
+```
+Write time:    "handler logic" [[vctx:src/handler.ts#L30-L45@a1b2c3d4]]
+After change:  vericontext verify → ❌ hash_mismatch (a1b2c3d4 ≠ f5e6d7c8)
+```
+
+**One broken citation → entire doc fails.** Fail-closed by design.
+
+## Setup
+
+```bash
+npx skills add amsminn/vericontext --skill vericontext-enforcer
+```
+
+Detects your agent (Claude Code, Codex, Antigravity, Cursor, Windsurf, OpenCode, …) and installs to the right path. Supports [40+ agents](https://github.com/vercel-labs/skills).
+
+To uninstall:
+
+```bash
+npx skills remove vericontext-enforcer
+```
+
+Once installed, the agent automatically:
+- Inserts `[[vctx:...]]` citations when referencing code in docs
+- Runs `vctx_verify_workspace` before commits and plan finalization
+- Flags stale citations for update
+
+<details>
+<summary>Manual install per agent</summary>
+
+The skill lives at `skills/vericontext-enforcer/SKILL.md` in this repo. Copy it to the right place for your agent:
+
+| Agent | Skill path | Also needs MCP? |
+|-------|-----------|-----------------|
+| **Claude Code** | `.claude/skills/vericontext-enforcer/` | No (skill handles it) |
+| **Antigravity** | `~/.gemini/antigravity/skills/vericontext-enforcer/` | No |
+| **Codex** | `.codex/skills/vericontext-enforcer/` | Yes |
+| **Cursor** | `.cursor/rules/vericontext.mdc` | Yes |
+| **Windsurf** | `.windsurf/rules/vericontext.md` | Yes |
+| **OpenCode** | Project rules | Yes |
+
+For agents that need MCP, add the server to your config:
+
+```json
+{ "mcpServers": { "vericontext": { "command": "npx", "args": ["-y", "vericontext", "mcp"] } } }
+```
+
+MCP tools exposed: `vctx_cite`, `vctx_claim`, `vctx_verify_workspace`
+
+</details>
+
+## GitHub Actions
+
+Add a step to any workflow:
+
+```yaml
+- name: Verify docs
+  run: npx -y vericontext verify workspace --root . --in-path README.md --json
+```
+
+Stale citation → CI red.
+
+### Pre-commit Hook
+
+```bash
+# .husky/pre-commit
+npx vericontext verify workspace --root . --in-path README.md --json
+```
+
+## How It Works
+
+```
+┌──────────┐    cite     ┌────────────────────────────────────┐
+│   file   │ ─────────→  │ [[vctx:path#L1-L2@<sha256-8>]]     │
+└──────────┘             └────────────────────────────────────┘
+                                       │
+┌──────────┐   verify    ┌─────────────▼──────────────────────┐
+│   file   │ ─────────→  │  hash match? → ok : hash_mismatch  │
+│(changed?)│             └────────────────────────────────────┘
+└──────────┘
+```
+
+1. **Cite** — snapshot a file's line range with its SHA-256 hash
+2. **Claim** — declare structure facts: `exists-file`, `exists-dir`, `missing`
+3. **Verify** — check every citation and claim in a doc. One failure → whole doc fails
+
+### Claim Syntax
+
+```
+Citation:    [[vctx:<path>#L<start>-L<end>@<hash8>]]
+Exists:      [[vctx-exists:<path>]]
+Exists-file: [[vctx-exists-file:<path>]]
+Exists-dir:  [[vctx-exists-dir:<path>/]]
+Missing:     [[vctx-missing:<path>]]
+```
+
+Claims can be hidden in HTML comments so they don't clutter the doc:
+
+```html
+The auth module handles login.
+<!-- [[vctx:src/auth.ts#L1-L50@abcd1234]] -->
+```
+
+### Features
+
+| | Feature | Description |
+|---|---|---|
+| # | **Hash citations** | Cite file line ranges with SHA-256 content hashes |
+| 📁 | **Structure claims** | Assert `exists`, `exists-file`, `exists-dir`, `missing` |
+| 🔒 | **Fail-closed** | One broken claim → entire verification fails |
+| 🚧 | **Root jail** | Repo-relative paths only. `../` traversal blocked |
+| 📟 | **CLI + MCP** | Same logic as both CLI and MCP stdio server |
+| 🔤 | **Deterministic** | UTF-8 only, LF-normalized, symlinks and binaries skipped |
+
+## CLI Reference
+
+<details>
+<summary><b>Install</b></summary>
+
+```bash
+npm install -g vericontext
+```
+
+Or use directly via `npx`:
+
+```bash
+npx vericontext --help
+```
+
+</details>
+
+<details>
+<summary><code>cite</code> — generate a code citation</summary>
+
+```bash
+npx vericontext cite --root <dir> --path <file> --start-line <n> --end-line <n> [--json]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--root` | Yes | Repository root directory |
+| `--path` | Yes | File path relative to root |
+| `--start-line` | Yes | Start line (1-based) |
+| `--end-line` | Yes | End line (1-based) |
+| `--json` | No | JSON output |
+
+</details>
+
+<details>
+<summary><code>claim</code> — generate a structure claim</summary>
+
+```bash
+npx vericontext claim --root <dir> --kind <kind> --path <path> [--json]
+```
+
+`--kind`: `exists` | `exists-file` | `exists-dir` | `missing`
+
+</details>
+
+<details>
+<summary><code>verify workspace</code> — verify all claims in a document</summary>
+
+```bash
+npx vericontext verify workspace --root <dir> (--in-path <doc> | --text <text>) [--json]
+```
+
+| Exit Code | Meaning |
+|-----------|---------|
+| `0` | All citations and claims valid |
+| `1` | One or more failures, or input error |
+
+```json
+{
+  "ok": false,
+  "total": 5,
+  "ok_count": 4,
+  "fail_count": 1,
+  "results": [
+    { "claim": "[[vctx:src/foo.ts#L1-L3@deadbeef]]", "ok": false, "reason": "hash_mismatch" }
+  ]
+}
+```
+
+</details>
+
+<details>
+<summary><b>Error reasons</b></summary>
+
+| Reason | Meaning |
+|--------|---------|
+| `hash_mismatch` | Cited content has changed |
+| `file_missing` | File does not exist |
+| `path_escape` | Path escapes root jail |
+| `range_invalid` | Line range out of bounds |
+| `binary_file` | Binary file (null byte detected) |
+| `symlink_skipped` | Symlink (skipped for determinism) |
+| `invalid_input` | Malformed input |
+
+</details>
+
+## Self-Verifying Docs
+
+This README itself contains hidden VeriContext claims and is verifiable:
+
+<!-- [[vctx-exists-dir:src/]] -->
+<!-- [[vctx-exists-file:src/cli.ts]] -->
+<!-- [[vctx-exists-file:src/mcp/server.ts]] -->
+<!-- [[vctx-missing:tmp-output/]] -->
+
+```bash
+npx vericontext verify workspace --root . --in-path README.md --json
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.js

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/core/file.ts
+import fs from "fs/promises";
+import { createHash } from "crypto";
+var UTF8_DECODER = new TextDecoder("utf-8", { fatal: true });
+function normalizeEol(text) {
+  return text.replace(/\r\n?/g, "\n");
+}
+async function readCanonicalText(absolutePath) {
+  let stats;
+  try {
+    stats = await fs.lstat(absolutePath);
+  } catch {
+    return { ok: false, reason: "file_missing" };
+  }
+  if (stats.isSymbolicLink()) {
+    return { ok: false, reason: "symlink_skipped" };
+  }
+  if (!stats.isFile()) {
+    return { ok: false, reason: "not_a_file" };
+  }
+  const bytes = await fs.readFile(absolutePath);
+  const probe = bytes.subarray(0, 8192);
+  if (probe.includes(0)) {
+    return { ok: false, reason: "binary_file" };
+  }
+  let decoded;
+  try {
+    decoded = UTF8_DECODER.decode(bytes);
+  } catch {
+    return { ok: false, reason: "invalid_utf8" };
+  }
+  const canonical = normalizeEol(decoded);
+  const lines = canonical.split("\n");
+  return { ok: true, text: canonical, lines };
+}
+function hashSha256Hex(value) {
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function hashLineSpan(lines, startLine, endLine) {
+  if (!Number.isInteger(startLine) || !Number.isInteger(endLine) || startLine < 1 || endLine < startLine) {
+    return { ok: false, reason: "range_invalid" };
+  }
+  if (endLine > lines.length) {
+    return { ok: false, reason: "range_invalid" };
+  }
+  const startIdx = startLine - 1;
+  const endIdx = endLine;
+  const span = lines.slice(startIdx, endIdx).join("\n");
+  return { ok: true, sha256_full: hashSha256Hex(span) };
+}
+
+// src/core/pathing.ts
+import path from "path";
+function normalizePathForClaim(inputPath) {
+  const normalized = inputPath.replaceAll("\\", "/").replace(/^\.\//, "");
+  if (normalized.length > 0 && normalized.endsWith("/")) {
+    return normalized;
+  }
+  return normalized;
+}
+function resolveUnderRoot(root, inputPath) {
+  if (path.isAbsolute(inputPath)) {
+    return { ok: false, reason: "invalid_path" };
+  }
+  const cleaned = normalizePathForClaim(inputPath);
+  if (cleaned.length === 0 || cleaned === ".") {
+    return { ok: false, reason: "invalid_path" };
+  }
+  const rootAbs = path.resolve(root);
+  const absolutePath = path.resolve(rootAbs, cleaned);
+  const rel = path.relative(rootAbs, absolutePath);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    return { ok: false, reason: "path_escape" };
+  }
+  const normalizedPath = rel.split(path.sep).join("/");
+  if (normalizedPath.length === 0 || normalizedPath.startsWith("../") || normalizedPath === "..") {
+    return { ok: false, reason: "path_escape" };
+  }
+  return { ok: true, normalizedPath, absolutePath };
+}
+
+// src/cite/citation.ts
+var CITATION_REGEX = /\[\[vctx:([^#\]]+)#L([0-9]+)-L([0-9]+)@([a-f0-9]{8})\]\]/g;
+function renderCitation(path2, startLine, endLine, sha256Full) {
+  const hash8 = sha256Full.slice(0, 8);
+  return `[[vctx:${path2}#L${startLine}-L${endLine}@${hash8}]]`;
+}
+function parseCitations(text) {
+  const output = [];
+  for (const match of text.matchAll(CITATION_REGEX)) {
+    const path2 = match[1];
+    const startLine = Number.parseInt(match[2], 10);
+    const endLine = Number.parseInt(match[3], 10);
+    const hash8 = match[4];
+    output.push({ path: path2, startLine, endLine, hash8, raw: match[0] });
+  }
+  return output;
+}
+async function generateCitation(input) {
+  const resolved = resolveUnderRoot(input.root, input.path);
+  if (!resolved.ok) {
+    return { ok: false, reason: resolved.reason };
+  }
+  const file = await readCanonicalText(resolved.absolutePath);
+  if (!file.ok) {
+    return { ok: false, reason: file.reason };
+  }
+  const span = hashLineSpan(file.lines, input.startLine, input.endLine);
+  if (!span.ok) {
+    return { ok: false, reason: span.reason };
+  }
+  const citation = renderCitation(resolved.normalizedPath, input.startLine, input.endLine, span.sha256_full);
+  return {
+    ok: true,
+    citation,
+    sha256_full: span.sha256_full
+  };
+}
+
+// src/cite/claim.ts
+import fs2 from "fs/promises";
+var STRUCTURE_REGEX = /\[\[vctx-(exists|exists-file|exists-dir|missing):([^\]]+)\]\]/g;
+function parseStructureClaims(text) {
+  const output = [];
+  for (const match of text.matchAll(STRUCTURE_REGEX)) {
+    output.push({ kind: match[1], path: match[2], raw: match[0] });
+  }
+  return output;
+}
+function renderStructureClaim(kind, normalizedPath) {
+  return `[[vctx-${kind}:${normalizedPath}]]`;
+}
+function generateStructureClaim(input) {
+  const resolved = resolveUnderRoot(input.root, input.path);
+  if (!resolved.ok) {
+    return { ok: false, reason: resolved.reason };
+  }
+  let normalizedPath = resolved.normalizedPath;
+  if (input.kind === "exists-dir" && input.path.endsWith("/") && !normalizedPath.endsWith("/")) {
+    normalizedPath = `${normalizedPath}/`;
+  }
+  return {
+    ok: true,
+    claim: renderStructureClaim(input.kind, normalizedPath),
+    kind: input.kind,
+    normalized_path: normalizedPath
+  };
+}
+async function verifyStructureKind(input) {
+  const resolved = resolveUnderRoot(input.root, input.path);
+  if (!resolved.ok) {
+    return { ok: false, reason: resolved.reason };
+  }
+  let stats = null;
+  try {
+    stats = await fs2.lstat(resolved.absolutePath);
+  } catch {
+    stats = null;
+  }
+  if (input.kind === "missing") {
+    return stats ? { ok: false, reason: "exists" } : { ok: true };
+  }
+  if (!stats) {
+    return { ok: false, reason: "missing" };
+  }
+  if (input.kind === "exists") {
+    return { ok: true };
+  }
+  if (input.kind === "exists-file") {
+    return stats.isFile() ? { ok: true } : { ok: false, reason: "not_file" };
+  }
+  return stats.isDirectory() ? { ok: true } : { ok: false, reason: "not_dir" };
+}
+
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/verify/workspace.ts
+import fs3 from "fs/promises";
+async function readVerifyText(input) {
+  const hasInPath = typeof input.inPath === "string";
+  const hasText = typeof input.text === "string";
+  if (hasInPath === hasText) {
+    return { reason: "invalid_input" };
+  }
+  if (hasText) {
+    return input.text;
+  }
+  const resolved = resolveUnderRoot(input.root, input.inPath);
+  if (!resolved.ok) {
+    return { reason: resolved.reason };
+  }
+  let stats;
+  try {
+    stats = await fs3.lstat(resolved.absolutePath);
+  } catch {
+    return { reason: "file_missing" };
+  }
+  if (!stats.isFile()) {
+    return { reason: "not_a_file" };
+  }
+  const raw = await fs3.readFile(resolved.absolutePath, "utf8");
+  return raw.replace(/\r\n?/g, "\n");
+}
+async function verifyWorkspace(input) {
+  const doc = await readVerifyText(input);
+  if (typeof doc !== "string") {
+    return { ok: false, reason: doc.reason };
+  }
+  const citationTokens = parseCitations(doc);
+  const structureTokens = parseStructureClaims(doc);
+  const results = [];
+  for (const token of citationTokens) {
+    const resolved = resolveUnderRoot(input.root, token.path);
+    if (!resolved.ok) {
+      results.push({ claim: token.raw, kind: "citation", ok: false, reason: resolved.reason });
+      continue;
+    }
+    const file = await readCanonicalText(resolved.absolutePath);
+    if (!file.ok) {
+      results.push({ claim: token.raw, kind: "citation", ok: false, reason: file.reason });
+      continue;
+    }
+    const span = hashLineSpan(file.lines, token.startLine, token.endLine);
+    if (!span.ok) {
+      results.push({ claim: token.raw, kind: "citation", ok: false, reason: span.reason });
+      continue;
+    }
+    const hash8 = span.sha256_full.slice(0, 8);
+    if (hash8 !== token.hash8) {
+      results.push({ claim: token.raw, kind: "citation", ok: false, reason: "hash_mismatch" });
+      continue;
+    }
+    results.push({ claim: token.raw, kind: "citation", ok: true });
+  }
+  for (const token of structureTokens) {
+    const structure = await verifyStructureKind({
+      root: input.root,
+      kind: token.kind,
+      path: token.path
+    });
+    if (!structure.ok) {
+      results.push({ claim: token.raw, kind: "structure", ok: false, reason: structure.reason });
+      continue;
+    }
+    results.push({ claim: token.raw, kind: "structure", ok: true });
+  }
+  const total = results.length;
+  const ok_count = results.filter((r) => r.ok).length;
+  const fail_count = total - ok_count;
+  return {
+    ok: fail_count === 0,
+    total,
+    ok_count,
+    fail_count,
+    results
+  };
+}
+
+// src/mcp/server.ts
+function textJson(value) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value) }]
+  };
+}
+async function runMcpServer() {
+  const server = new McpServer({
+    name: "vericontext",
+    version: "0.1.0"
+  });
+  server.registerTool(
+    "vctx_cite",
+    {
+      description: "Generate a verifiable citation for a file line-span.",
+      inputSchema: {
+        root: z.string(),
+        path: z.string(),
+        start_line: z.number().int().positive(),
+        end_line: z.number().int().positive()
+      }
+    },
+    async ({ root, path: path2, start_line, end_line }) => {
+      const result = await generateCitation({ root, path: path2, startLine: start_line, endLine: end_line });
+      return textJson(result);
+    }
+  );
+  server.registerTool(
+    "vctx_claim",
+    {
+      description: "Generate a structure claim string for a path.",
+      inputSchema: {
+        root: z.string(),
+        kind: z.enum(["exists", "exists-file", "exists-dir", "missing"]),
+        path: z.string()
+      }
+    },
+    async ({ root, kind, path: path2 }) => {
+      const result = generateStructureClaim({ root, kind, path: path2 });
+      return textJson(result);
+    }
+  );
+  server.registerTool(
+    "vctx_verify_workspace",
+    {
+      description: "Verify all in-document VCC claims against current workspace.",
+      inputSchema: {
+        root: z.string(),
+        in_path: z.string().optional(),
+        text: z.string().optional()
+      }
+    },
+    async ({ root, in_path, text }) => {
+      const result = await verifyWorkspace({ root, inPath: in_path, text });
+      return textJson(result);
+    }
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// src/cli.ts
+function printResult(jsonMode, result, fallbackText) {
+  if (jsonMode) {
+    process.stdout.write(`${JSON.stringify(result)}
+`);
+    return;
+  }
+  if (fallbackText) {
+    process.stdout.write(`${fallbackText}
+`);
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+}
+function withRootAndJson(command) {
+  return command.requiredOption("--root <root>", "Repository root").option("--json", "Output as JSON", false);
+}
+async function main() {
+  const program = new Command();
+  program.name("vericontext").description("Verifiable Context Compactor").version("0.1.0");
+  withRootAndJson(
+    program.command("cite").description("Generate a verifiable citation for a file line span").requiredOption("--path <path>", "File path under root").requiredOption("--start-line <startLine>", "1-based start line", Number.parseInt).requiredOption("--end-line <endLine>", "1-based end line", Number.parseInt)
+  ).action(async (opts) => {
+    const result = await generateCitation({
+      root: opts.root,
+      path: opts.path,
+      startLine: opts.startLine,
+      endLine: opts.endLine
+    });
+    const text = result.ok ? result.citation : void 0;
+    printResult(Boolean(opts.json), result, text);
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
+  });
+  withRootAndJson(
+    program.command("claim").description("Generate a structure claim").requiredOption("--kind <kind>", "exists|exists-file|exists-dir|missing").requiredOption("--path <path>", "Path under root")
+  ).action(async (opts) => {
+    const kinds = /* @__PURE__ */ new Set(["exists", "exists-file", "exists-dir", "missing"]);
+    if (!kinds.has(opts.kind)) {
+      const err = { ok: false, reason: "invalid_input" };
+      printResult(Boolean(opts.json), err);
+      process.exitCode = 1;
+      return;
+    }
+    const result = generateStructureClaim({ root: opts.root, kind: opts.kind, path: opts.path });
+    const text = result.ok ? result.claim : void 0;
+    printResult(Boolean(opts.json), result, text);
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
+  });
+  const verify = program.command("verify").description("Verification commands");
+  withRootAndJson(
+    verify.command("workspace").description("Verify all VCC claims from an input document or inline text").option("--in-path <inPath>", "Input document path under root").option("--text <text>", "Inline document text")
+  ).action(async (opts) => {
+    const result = await verifyWorkspace({
+      root: opts.root,
+      inPath: opts.inPath,
+      text: opts.text
+    });
+    printResult(Boolean(opts.json), result);
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
+  });
+  program.command("mcp").description("Run MCP server over stdio").action(async () => {
+    await runMcpServer();
+  });
+  await program.parseAsync(process.argv);
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : "unknown_error";
+  process.stderr.write(`${message}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts","../src/core/file.ts","../src/core/pathing.ts","../src/cite/citation.ts","../src/cite/claim.ts","../src/mcp/server.ts","../src/verify/workspace.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport { Command } from \"commander\";\n\nimport { generateCitation } from \"./cite/citation.js\";\nimport { generateStructureClaim } from \"./cite/claim.js\";\nimport { runMcpServer } from \"./mcp/server.js\";\nimport { verifyWorkspace } from \"./verify/workspace.js\";\n\nfunction printResult(jsonMode: boolean, result: unknown, fallbackText?: string): void {\n  if (jsonMode) {\n    process.stdout.write(`${JSON.stringify(result)}\\n`);\n    return;\n  }\n  if (fallbackText) {\n    process.stdout.write(`${fallbackText}\\n`);\n    return;\n  }\n  process.stdout.write(`${JSON.stringify(result, null, 2)}\\n`);\n}\n\nfunction withRootAndJson(command: Command): Command {\n  return command\n    .requiredOption(\"--root <root>\", \"Repository root\")\n    .option(\"--json\", \"Output as JSON\", false);\n}\n\nasync function main(): Promise<void> {\n  const program = new Command();\n\n  program\n    .name(\"vericontext\")\n    .description(\"Verifiable Context Compactor\")\n    .version(\"0.1.0\");\n\n  withRootAndJson(\n    program\n      .command(\"cite\")\n      .description(\"Generate a verifiable citation for a file line span\")\n      .requiredOption(\"--path <path>\", \"File path under root\")\n      .requiredOption(\"--start-line <startLine>\", \"1-based start line\", Number.parseInt)\n      .requiredOption(\"--end-line <endLine>\", \"1-based end line\", Number.parseInt),\n  ).action(async (opts) => {\n    const result = await generateCitation({\n      root: opts.root,\n      path: opts.path,\n      startLine: opts.startLine,\n      endLine: opts.endLine,\n    });\n    const text = result.ok ? result.citation : undefined;\n    printResult(Boolean(opts.json), result, text);\n    if (!result.ok) {\n      process.exitCode = 1;\n    }\n  });\n\n  withRootAndJson(\n    program\n      .command(\"claim\")\n      .description(\"Generate a structure claim\")\n      .requiredOption(\"--kind <kind>\", \"exists|exists-file|exists-dir|missing\")\n      .requiredOption(\"--path <path>\", \"Path under root\"),\n  ).action(async (opts) => {\n    const kinds = new Set([\"exists\", \"exists-file\", \"exists-dir\", \"missing\"]);\n    if (!kinds.has(opts.kind)) {\n      const err = { ok: false, reason: \"invalid_input\" };\n      printResult(Boolean(opts.json), err);\n      process.exitCode = 1;\n      return;\n    }\n\n    const result = generateStructureClaim({ root: opts.root, kind: opts.kind, path: opts.path });\n    const text = result.ok ? result.claim : undefined;\n    printResult(Boolean(opts.json), result, text);\n    if (!result.ok) {\n      process.exitCode = 1;\n    }\n  });\n\n  const verify = program.command(\"verify\").description(\"Verification commands\");\n\n  withRootAndJson(\n    verify\n      .command(\"workspace\")\n      .description(\"Verify all VCC claims from an input document or inline text\")\n      .option(\"--in-path <inPath>\", \"Input document path under root\")\n      .option(\"--text <text>\", \"Inline document text\"),\n  ).action(async (opts) => {\n    const result = await verifyWorkspace({\n      root: opts.root,\n      inPath: opts.inPath,\n      text: opts.text,\n    });\n    printResult(Boolean(opts.json), result);\n    if (!result.ok) {\n      process.exitCode = 1;\n    }\n  });\n\n  program.command(\"mcp\").description(\"Run MCP server over stdio\").action(async () => {\n    await runMcpServer();\n  });\n\n  await program.parseAsync(process.argv);\n}\n\nmain().catch((error: unknown) => {\n  const message = error instanceof Error ? error.message : \"unknown_error\";\n  process.stderr.write(`${message}\\n`);\n  process.exit(1);\n});\n","import fs from \"node:fs/promises\";\nimport { createHash } from \"node:crypto\";\n\nimport type { ErrorReason } from \"../types.js\";\n\nexport interface FileTextOk {\n  ok: true;\n  text: string;\n  lines: string[];\n}\n\nexport interface FileTextErr {\n  ok: false;\n  reason: ErrorReason;\n}\n\nconst UTF8_DECODER = new TextDecoder(\"utf-8\", { fatal: true });\n\nexport function normalizeEol(text: string): string {\n  return text.replace(/\\r\\n?/g, \"\\n\");\n}\n\nexport async function readCanonicalText(absolutePath: string): Promise<FileTextOk | FileTextErr> {\n  let stats;\n  try {\n    stats = await fs.lstat(absolutePath);\n  } catch {\n    return { ok: false, reason: \"file_missing\" };\n  }\n\n  if (stats.isSymbolicLink()) {\n    return { ok: false, reason: \"symlink_skipped\" };\n  }\n\n  if (!stats.isFile()) {\n    return { ok: false, reason: \"not_a_file\" };\n  }\n\n  const bytes = await fs.readFile(absolutePath);\n  const probe = bytes.subarray(0, 8192);\n  if (probe.includes(0)) {\n    return { ok: false, reason: \"binary_file\" };\n  }\n\n  let decoded: string;\n  try {\n    decoded = UTF8_DECODER.decode(bytes);\n  } catch {\n    return { ok: false, reason: \"invalid_utf8\" };\n  }\n\n  const canonical = normalizeEol(decoded);\n  const lines = canonical.split(\"\\n\");\n  return { ok: true, text: canonical, lines };\n}\n\nexport function hashSha256Hex(value: string): string {\n  return createHash(\"sha256\").update(value, \"utf8\").digest(\"hex\");\n}\n\nexport interface SpanHashOk {\n  ok: true;\n  sha256_full: string;\n}\n\nexport interface SpanHashErr {\n  ok: false;\n  reason: ErrorReason;\n}\n\nexport function hashLineSpan(lines: string[], startLine: number, endLine: number): SpanHashOk | SpanHashErr {\n  if (!Number.isInteger(startLine) || !Number.isInteger(endLine) || startLine < 1 || endLine < startLine) {\n    return { ok: false, reason: \"range_invalid\" };\n  }\n  if (endLine > lines.length) {\n    return { ok: false, reason: \"range_invalid\" };\n  }\n\n  const startIdx = startLine - 1;\n  const endIdx = endLine;\n  const span = lines.slice(startIdx, endIdx).join(\"\\n\");\n  return { ok: true, sha256_full: hashSha256Hex(span) };\n}\n","import path from \"node:path\";\n\nimport type { ErrorReason } from \"../types.js\";\n\nexport interface PathOk {\n  ok: true;\n  normalizedPath: string;\n  absolutePath: string;\n}\n\nexport interface PathErr {\n  ok: false;\n  reason: ErrorReason;\n}\n\nexport const DEFAULT_EXCLUDES = [\".git\", \"node_modules\", \"dist\", \"build\"] as const;\n\nexport function normalizePathForClaim(inputPath: string): string {\n  const normalized = inputPath.replaceAll(\"\\\\\", \"/\").replace(/^\\.\\//, \"\");\n  if (normalized.length > 0 && normalized.endsWith(\"/\")) {\n    return normalized;\n  }\n  return normalized;\n}\n\nexport function resolveUnderRoot(root: string, inputPath: string): PathOk | PathErr {\n  if (path.isAbsolute(inputPath)) {\n    return { ok: false, reason: \"invalid_path\" };\n  }\n\n  const cleaned = normalizePathForClaim(inputPath);\n  if (cleaned.length === 0 || cleaned === \".\") {\n    return { ok: false, reason: \"invalid_path\" };\n  }\n\n  const rootAbs = path.resolve(root);\n  const absolutePath = path.resolve(rootAbs, cleaned);\n  const rel = path.relative(rootAbs, absolutePath);\n\n  if (rel.startsWith(\"..\") || path.isAbsolute(rel)) {\n    return { ok: false, reason: \"path_escape\" };\n  }\n\n  const normalizedPath = rel.split(path.sep).join(\"/\");\n  if (normalizedPath.length === 0 || normalizedPath.startsWith(\"../\") || normalizedPath === \"..\") {\n    return { ok: false, reason: \"path_escape\" };\n  }\n\n  return { ok: true, normalizedPath, absolutePath };\n}\n\nexport function isExcludedPath(normalizedPath: string): boolean {\n  return DEFAULT_EXCLUDES.some((prefix) => normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`));\n}\n","import { readCanonicalText, hashLineSpan } from \"../core/file.js\";\nimport { resolveUnderRoot } from \"../core/pathing.js\";\nimport type { CiteSuccess, ErrorReason } from \"../types.js\";\n\nexport interface CitationParts {\n  path: string;\n  startLine: number;\n  endLine: number;\n  hash8: string;\n  raw: string;\n}\n\nexport interface CitationError {\n  ok: false;\n  reason: ErrorReason;\n}\n\nexport const CITATION_REGEX = /\\[\\[vctx:([^#\\]]+)#L([0-9]+)-L([0-9]+)@([a-f0-9]{8})\\]\\]/g;\n\nexport function renderCitation(path: string, startLine: number, endLine: number, sha256Full: string): string {\n  const hash8 = sha256Full.slice(0, 8);\n  return `[[vctx:${path}#L${startLine}-L${endLine}@${hash8}]]`;\n}\n\nexport function parseCitations(text: string): CitationParts[] {\n  const output: CitationParts[] = [];\n  for (const match of text.matchAll(CITATION_REGEX)) {\n    const path = match[1];\n    const startLine = Number.parseInt(match[2], 10);\n    const endLine = Number.parseInt(match[3], 10);\n    const hash8 = match[4];\n    output.push({ path, startLine, endLine, hash8, raw: match[0] });\n  }\n  return output;\n}\n\nexport async function generateCitation(input: {\n  root: string;\n  path: string;\n  startLine: number;\n  endLine: number;\n}): Promise<CiteSuccess | CitationError> {\n  const resolved = resolveUnderRoot(input.root, input.path);\n  if (!resolved.ok) {\n    return { ok: false, reason: resolved.reason };\n  }\n\n  const file = await readCanonicalText(resolved.absolutePath);\n  if (!file.ok) {\n    return { ok: false, reason: file.reason };\n  }\n\n  const span = hashLineSpan(file.lines, input.startLine, input.endLine);\n  if (!span.ok) {\n    return { ok: false, reason: span.reason };\n  }\n\n  const citation = renderCitation(resolved.normalizedPath, input.startLine, input.endLine, span.sha256_full);\n  return {\n    ok: true,\n    citation,\n    sha256_full: span.sha256_full,\n  };\n}\n","import fs from \"node:fs/promises\";\n\nimport { resolveUnderRoot } from \"../core/pathing.js\";\nimport type { ClaimSuccess, ErrorReason, StructureKind } from \"../types.js\";\n\nexport interface ClaimError {\n  ok: false;\n  reason: ErrorReason;\n}\n\nexport const STRUCTURE_REGEX = /\\[\\[vctx-(exists|exists-file|exists-dir|missing):([^\\]]+)\\]\\]/g;\n\nexport interface StructureToken {\n  kind: StructureKind;\n  path: string;\n  raw: string;\n}\n\nexport function parseStructureClaims(text: string): StructureToken[] {\n  const output: StructureToken[] = [];\n  for (const match of text.matchAll(STRUCTURE_REGEX)) {\n    output.push({ kind: match[1] as StructureKind, path: match[2], raw: match[0] });\n  }\n  return output;\n}\n\nexport function renderStructureClaim(kind: StructureKind, normalizedPath: string): string {\n  return `[[vctx-${kind}:${normalizedPath}]]`;\n}\n\nexport function generateStructureClaim(input: {\n  root: string;\n  kind: StructureKind;\n  path: string;\n}): ClaimSuccess | ClaimError {\n  const resolved = resolveUnderRoot(input.root, input.path);\n  if (!resolved.ok) {\n    return { ok: false, reason: resolved.reason };\n  }\n\n  let normalizedPath = resolved.normalizedPath;\n  if (input.kind === \"exists-dir\" && input.path.endsWith(\"/\") && !normalizedPath.endsWith(\"/\")) {\n    normalizedPath = `${normalizedPath}/`;\n  }\n\n  return {\n    ok: true,\n    claim: renderStructureClaim(input.kind, normalizedPath),\n    kind: input.kind,\n    normalized_path: normalizedPath,\n  };\n}\n\nexport async function verifyStructureKind(input: {\n  root: string;\n  kind: StructureKind;\n  path: string;\n}): Promise<{ ok: true } | { ok: false; reason: ErrorReason }> {\n  const resolved = resolveUnderRoot(input.root, input.path);\n  if (!resolved.ok) {\n    return { ok: false, reason: resolved.reason };\n  }\n\n  let stats: Awaited<ReturnType<typeof fs.lstat>> | null = null;\n  try {\n    stats = await fs.lstat(resolved.absolutePath);\n  } catch {\n    stats = null;\n  }\n\n  if (input.kind === \"missing\") {\n    return stats ? { ok: false, reason: \"exists\" } : { ok: true };\n  }\n\n  if (!stats) {\n    return { ok: false, reason: \"missing\" };\n  }\n\n  if (input.kind === \"exists\") {\n    return { ok: true };\n  }\n  if (input.kind === \"exists-file\") {\n    return stats.isFile() ? { ok: true } : { ok: false, reason: \"not_file\" };\n  }\n  return stats.isDirectory() ? { ok: true } : { ok: false, reason: \"not_dir\" };\n}\n","import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { z } from \"zod\";\n\nimport { generateCitation } from \"../cite/citation.js\";\nimport { generateStructureClaim } from \"../cite/claim.js\";\nimport { verifyWorkspace } from \"../verify/workspace.js\";\n\nfunction textJson(value: unknown): { content: Array<{ type: \"text\"; text: string }> } {\n  return {\n    content: [{ type: \"text\", text: JSON.stringify(value) }],\n  };\n}\n\nexport async function runMcpServer(): Promise<void> {\n  const server = new McpServer({\n    name: \"vericontext\",\n    version: \"0.1.0\",\n  });\n\n  server.registerTool(\n    \"vctx_cite\",\n    {\n      description: \"Generate a verifiable citation for a file line-span.\",\n      inputSchema: {\n        root: z.string(),\n        path: z.string(),\n        start_line: z.number().int().positive(),\n        end_line: z.number().int().positive(),\n      },\n    },\n    async ({ root, path, start_line, end_line }) => {\n      const result = await generateCitation({ root, path, startLine: start_line, endLine: end_line });\n      return textJson(result);\n    },\n  );\n\n  server.registerTool(\n    \"vctx_claim\",\n    {\n      description: \"Generate a structure claim string for a path.\",\n      inputSchema: {\n        root: z.string(),\n        kind: z.enum([\"exists\", \"exists-file\", \"exists-dir\", \"missing\"]),\n        path: z.string(),\n      },\n    },\n    async ({ root, kind, path }) => {\n      const result = generateStructureClaim({ root, kind, path });\n      return textJson(result);\n    },\n  );\n\n  server.registerTool(\n    \"vctx_verify_workspace\",\n    {\n      description: \"Verify all in-document VCC claims against current workspace.\",\n      inputSchema: {\n        root: z.string(),\n        in_path: z.string().optional(),\n        text: z.string().optional(),\n      },\n    },\n    async ({ root, in_path, text }) => {\n      const result = await verifyWorkspace({ root, inPath: in_path, text });\n      return textJson(result);\n    },\n  );\n\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n}\n","import fs from \"node:fs/promises\";\n\nimport { parseCitations } from \"../cite/citation.js\";\nimport { parseStructureClaims, verifyStructureKind } from \"../cite/claim.js\";\nimport { readCanonicalText, hashLineSpan } from \"../core/file.js\";\nimport { resolveUnderRoot } from \"../core/pathing.js\";\nimport type { VerifyWorkspaceResult } from \"../types.js\";\nimport type { ErrorReason } from \"../types.js\";\n\nexport interface VerifyInput {\n  root: string;\n  inPath?: string;\n  text?: string;\n}\n\nexport async function readVerifyText(input: VerifyInput): Promise<string | { reason: ErrorReason }> {\n  const hasInPath = typeof input.inPath === \"string\";\n  const hasText = typeof input.text === \"string\";\n  if (hasInPath === hasText) {\n    return { reason: \"invalid_input\" };\n  }\n\n  if (hasText) {\n    return input.text as string;\n  }\n\n  const resolved = resolveUnderRoot(input.root, input.inPath as string);\n  if (!resolved.ok) {\n    return { reason: resolved.reason };\n  }\n\n  let stats;\n  try {\n    stats = await fs.lstat(resolved.absolutePath);\n  } catch {\n    return { reason: \"file_missing\" };\n  }\n  if (!stats.isFile()) {\n    return { reason: \"not_a_file\" };\n  }\n\n  const raw = await fs.readFile(resolved.absolutePath, \"utf8\");\n  return raw.replace(/\\r\\n?/g, \"\\n\");\n}\n\nexport async function verifyWorkspace(input: VerifyInput): Promise<VerifyWorkspaceResult | { ok: false; reason: ErrorReason }> {\n  const doc = await readVerifyText(input);\n  if (typeof doc !== \"string\") {\n    return { ok: false, reason: doc.reason };\n  }\n\n  const citationTokens = parseCitations(doc);\n  const structureTokens = parseStructureClaims(doc);\n  const results: VerifyWorkspaceResult[\"results\"] = [];\n\n  for (const token of citationTokens) {\n    const resolved = resolveUnderRoot(input.root, token.path);\n    if (!resolved.ok) {\n      results.push({ claim: token.raw, kind: \"citation\", ok: false, reason: resolved.reason });\n      continue;\n    }\n\n    const file = await readCanonicalText(resolved.absolutePath);\n    if (!file.ok) {\n      results.push({ claim: token.raw, kind: \"citation\", ok: false, reason: file.reason });\n      continue;\n    }\n\n    const span = hashLineSpan(file.lines, token.startLine, token.endLine);\n    if (!span.ok) {\n      results.push({ claim: token.raw, kind: \"citation\", ok: false, reason: span.reason });\n      continue;\n    }\n\n    const hash8 = span.sha256_full.slice(0, 8);\n    if (hash8 !== token.hash8) {\n      results.push({ claim: token.raw, kind: \"citation\", ok: false, reason: \"hash_mismatch\" });\n      continue;\n    }\n\n    results.push({ claim: token.raw, kind: \"citation\", ok: true });\n  }\n\n  for (const token of structureTokens) {\n    const structure = await verifyStructureKind({\n      root: input.root,\n      kind: token.kind,\n      path: token.path,\n    });\n\n    if (!structure.ok) {\n      results.push({ claim: token.raw, kind: \"structure\", ok: false, reason: structure.reason });\n      continue;\n    }\n    results.push({ claim: token.raw, kind: \"structure\", ok: true });\n  }\n\n  const total = results.length;\n  const ok_count = results.filter((r) => r.ok).length;\n  const fail_count = total - ok_count;\n\n  return {\n    ok: fail_count === 0,\n    total,\n    ok_count,\n    fail_count,\n    results,\n  };\n}\n"],"mappings":"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","names":["path","fs","fs","fs","fs","path"]}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "vericontext",
+  "version": "0.1.1",
+  "description": "Deterministic, hash-based verification for docs that reference code",
+  "type": "module",
+  "bin": {
+    "vericontext": "dist/cli.js",
+    "vcc": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "keywords": [
+    "documentation",
+    "verification",
+    "citation",
+    "hash",
+    "mcp",
+    "agents",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amsminn/vericontext.git"
+  },
+  "homepage": "https://github.com/amsminn/vericontext",
+  "license": "MIT",
+  "author": "amsminn",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "mcp:smoke": "tsx scripts/mcp-smoke.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.2",
+    "commander": "^14.0.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.4.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/skills/vericontext-enforcer/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: vericontext-enforcer
+description: >-
+  AI 에이전트가 문서(README, AGENTS.md, 플랜 등)를 작성·수정할 때 VeriContext
+  citation/claim을 자동으로 생성·삽입하도록 강제하고, 커밋·플랜 마무리 시점에
+  vctx_verify_workspace를 실행하여 모든 claim이 최신 상태인지 검증한다.
+  코드를 참조하는 모든 문서 작업에서 사용한다.
+  NOT for: 코드 자체의 수정, 테스트 작성, 빌드 작업.
+hooks:
+  PreToolUse:
+    - matcher: Edit
+      hooks:
+        - command: >-
+            echo '[vericontext-enforcer] Editing a file — remember to update
+            any vctx citations referencing changed lines.'
+---
+
+## Phase 1 — 참조 대상 식별 (Detect & Plan)
+
+문서를 작성하거나 수정하기 전에, 참조할 코드와 구조를 먼저 식별한다.
+
+### 1.1 참조 유형 분류
+
+| 참조 유형 | VeriContext 도구 | 실제 예시 |
+|-----------|-----------------|-----------|
+| 코드 라인 범위 | `vctx_cite` | <!-- [[vctx:src/cli.ts#L28-L34@2b4ed3f8]] --> |
+| 파일 존재 여부 | `vctx_claim --kind exists-file` | <!-- [[vctx-exists-file:src/cli.ts]] --> |
+| 디렉토리 존재 여부 | `vctx_claim --kind exists-dir` | <!-- [[vctx-exists-dir:src/]] --> |
+| 파일/디렉토리 부재 확인 | `vctx_claim --kind missing` | <!-- [[vctx-missing:tmp-output]] --> |
+
+> 위 예시는 모두 이 프로젝트에서 실제로 유효한 claim이다. `vctx_verify_workspace`로 검증하면 전부 `ok: true`.
+
+### 1.2 행동 규칙
+
+1. **코드를 언급하면 반드시 citation을 생성한다.** "이 함수는 X를 한다"라고 쓰려면, 해당 함수의 라인 범위를 `vctx_cite`로 인용한 뒤 토큰을 문서에 삽입한다.
+2. **프로젝트 구조를 언급하면 반드시 claim을 생성한다.** "src/ 디렉토리에는..."이라고 쓰려면 `vctx_claim --kind exists-dir`로 claim을 만든다.
+3. **외부 도구(read_file 등)로 코드를 읽었더라도**, 문서에 기술하기 전에 `vctx_cite`를 호출하여 citation 토큰을 확보한다.
+4. citation/claim 토큰은 **HTML 주석(`<!-- ... -->`)** 안에 넣거나, 관련 텍스트 바로 뒤에 inline으로 배치한다.
+
+## Phase 2 — Citation/Claim 생성 및 삽입 (Generate & Embed)
+
+### 2.1 CLI 사용법 (에이전트 환경 공통)
+
+**Citation 생성:**
+```bash
+vericontext cite --root <project-root> --path <file> --start-line <N> --end-line <M> --json
+```
+
+응답 예시:
+```json
+{ "ok": true, "citation": "[[vctx:src/cli.ts#L28-L34@2b4ed3f8]]", "sha256_full": "2b4ed3f8..." }
+```
+
+**Structure Claim 생성:**
+```bash
+vericontext claim --root <project-root> --kind exists-dir --path src/ --json
+```
+
+응답 예시:
+```json
+{ "ok": true, "claim": "[[vctx-exists-dir:src/]]", "kind": "exists-dir", "normalized_path": "src/" }
+```
+
+### 2.2 MCP 사용법 (MCP 지원 에이전트)
+
+MCP 도구 `vctx_cite`, `vctx_claim`을 직접 호출한다. 파라미터는 CLI와 동일하다.
+
+### 2.3 삽입 패턴
+
+**패턴 A — 인라인 (테이블, 코드맵에서 사용):**
+
+| CLI 진입점 | `src/cli.ts` | <!-- [[vctx:src/cli.ts#L28-L34@2b4ed3f8]] --> |
+
+**패턴 B — 섹션 끝 (설명 문단 뒤에 사용):**
+
+검증 로직은 claim 단위로 원자적으로 동작한다. 하나라도 실패하면 전체 결과가 `ok: false`가 된다.
+<!-- [[vctx:src/verify/workspace.ts#L46-L109@39dad95f]] -->
+
+**패턴 C — 구조 선언 (프로젝트 구조 설명에 사용):**
+
+├── src/          # production logic
+<!-- [[vctx-exists-dir:src/]] -->
+├── tests/        # unit + e2e tests
+<!-- [[vctx-exists-dir:tests/]] -->
+<!-- [[vctx-exists-file:package.json]] -->
+
+### 2.4 절대 금지 사항
+
+- citation 토큰을 수동으로 타이핑하지 않는다. 반드시 도구로 생성한다.
+- hash 값을 추측하거나 이전 값을 복사하지 않는다.
+- 존재하지 않는 파일에 대한 citation을 만들지 않는다.
+- claim 없이 "이 파일이 있다/없다"고 단언하지 않는다.
+
+## Phase 3 — 검증 및 강제 (Verify & Enforce)
+
+### 3.1 검증 타이밍
+
+다음 시점에 **반드시** 검증을 실행한다:
+
+1. **문서 작성/수정 완료 직후** — 커밋 전에 반드시 실행
+2. **플랜 마무리 시** — 플랜 문서에 포함된 모든 claim 검증
+3. **코드 수정 후** — 코드를 변경했다면, 해당 코드를 참조하는 문서의 claim 검증
+
+### 3.2 검증 실행
+
+**CLI:**
+```bash
+vericontext verify workspace --root <project-root> --in-path <document.md> --json
+```
+
+**MCP:**
+`vctx_verify_workspace` 도구를 `root`와 `in_path` 파라미터로 호출한다.
+
+**응답 예시 (성공):**
+```json
+{ "ok": true, "total": 3, "ok_count": 3, "fail_count": 0, "results": [...] }
+```
+
+**실패 시 응답 구조:**
+```json
+{ "ok": false, "total": N, "ok_count": M, "fail_count": N-M,
+  "results": [{ "claim": "<token>", "ok": false, "reason": "hash_mismatch|missing|range_invalid" }] }
+```
+`reason` 필드의 값에 따라 3.3의 대응 절차를 따른다.
+
+### 3.3 실패 시 대응 절차
+
+1. `hash_mismatch` → 해당 파일의 현재 라인 범위를 다시 읽고, `vctx_cite`로 새 citation을 생성하여 교체한다.
+2. `missing` / `not_file` / `not_dir` → 파일/디렉토리가 이동·삭제되었는지 확인하고, 문서 내용을 수정하거나 claim을 제거한다.
+3. `range_invalid` → 파일이 줄어들었다면 올바른 범위로 재인용한다.
+4. **모든 실패를 해결한 뒤 다시 검증을 실행한다.** `ok: true`가 될 때까지 반복한다.
+
+### 3.4 검증 통과 기준
+
+- `ok: true` — 커밋 또는 플랜 제출 가능
+- `ok: false` — **커밋/제출 불가**. 실패한 claim을 모두 수정해야 한다.
+
+> **원칙: Fail Closed.** 검증을 건너뛰거나, 실패한 채로 커밋하는 것은 이 스킬의 위반이다.
+
+## Phase 4 — 에이전트별 설정 가이드
+
+### Claude Code
+- MCP 서버로 `vericontext mcp`를 등록하면 `vctx_cite`, `vctx_claim`, `vctx_verify_workspace` 도구를 직접 사용할 수 있다.
+- 이 스킬은 `.claude/skills/vericontext-enforcer`에 symlink로 연결되어 자동 로드된다.
+
+### Codex (OpenAI)
+- CLI(`vericontext cite`, `vericontext claim`, `vericontext verify workspace`)를 Bash/shell 도구로 실행한다.
+- AGENTS.md에 이 스킬의 핵심 규칙이 요약되어 있어 Codex가 자동으로 읽는다.
+
+### OpenCode
+- MCP를 지원하는 경우 Claude Code와 동일하게 MCP 서버를 등록한다.
+- MCP 미지원 시 Codex와 동일하게 CLI + AGENTS.md 방식을 사용한다.
+
+### Antigravity / 기타
+- CLI 실행만 가능한 환경에서는 `scripts/verify-modified-docs.sh`를 실행하여 수정된 문서를 일괄 검증한다.
+- INSTRUCTIONS.md 또는 시스템 프롬프트에 Phase 1~3의 핵심 규칙을 복사하여 사용한다.
+
+## Reference File Index
+
+| File | Read When |
+|------|-----------|
+| `references/citation-format-guide.md` | citation/claim 문법을 정확히 알아야 할 때 |
+| `references/verification-playbook.md` | 검증 실패 시 구체적인 해결 절차가 필요할 때 |
+| `references/cross-agent-setup.md` | 새 에이전트 환경에 VeriContext를 설정할 때 |
+
+## Critical Rules
+
+1. **문서에 코드를 참조하면 반드시 `vctx_cite`로 citation을 생성한다.** 예외 없음.
+2. **커밋 전에 반드시 `vctx_verify_workspace`를 실행한다.** `ok: true`가 아니면 커밋하지 않는다.
+3. **citation 토큰을 수동으로 작성하지 않는다.** 항상 도구로 생성한다.
+4. **코드를 수정하면, 해당 코드를 참조하는 문서의 citation도 갱신한다.**
+5. **검증 실패를 무시하지 않는다.** Fail closed — 실패는 항상 수정해야 한다.

package/skills/vericontext-enforcer/evals/citation-enforcement.json

@@ -0,0 +1,27 @@
+[
+  {
+    "skills": ["vericontext-enforcer"],
+    "query": "README.md에 src/cli.ts의 main 함수에 대한 설명을 추가해줘",
+    "files": ["src/cli.ts", "README.md"],
+    "expected_behavior": [
+      "Agent begins Phase 1: identifies src/cli.ts as a code reference target",
+      "Agent calls vctx_cite (or vericontext cite CLI) with path=src/cli.ts and appropriate line range",
+      "Agent receives citation token with hash",
+      "Agent writes the description into README.md with the citation token embedded",
+      "Agent runs vctx_verify_workspace on README.md",
+      "Agent confirms ok: true before considering the task complete"
+    ]
+  },
+  {
+    "skills": ["vericontext-enforcer"],
+    "query": "AGENTS.md의 프로젝트 구조 섹션을 최신화해줘",
+    "files": ["AGENTS.md"],
+    "expected_behavior": [
+      "Agent begins Phase 1: identifies directory/file references in structure section",
+      "Agent calls vctx_claim for each directory and file mentioned",
+      "Agent embeds claim tokens as HTML comments in the structure section",
+      "Agent runs vctx_verify_workspace on AGENTS.md",
+      "Agent confirms ok: true before considering the task complete"
+    ]
+  }
+]

package/skills/vericontext-enforcer/evals/verification-workflow.json

@@ -0,0 +1,15 @@
+[
+  {
+    "skills": ["vericontext-enforcer"],
+    "query": "src/cli.ts를 수정했어. 관련 문서도 업데이트해줘",
+    "files": ["src/cli.ts", "README.md", "AGENTS.md"],
+    "expected_behavior": [
+      "Agent identifies documents that reference src/cli.ts by scanning for vctx citations",
+      "Agent runs vctx_verify_workspace on each document to find stale claims",
+      "For each failed claim, agent regenerates citation with updated content",
+      "Agent replaces stale citation tokens in the documents",
+      "Agent re-runs verification and confirms ok: true for all documents",
+      "Agent reports which documents and citations were updated"
+    ]
+  }
+]

package/skills/vericontext-enforcer/references/citation-format-guide.md

@@ -0,0 +1,52 @@
+# VeriContext Citation & Claim Format Guide
+
+## Citation (코드 라인 참조)
+
+### 형식
+````
+[[vctx:<relative-path>#L<start>-L<end>@<hash8>]]
+````
+
+### 구성 요소
+- `relative-path`: 프로젝트 루트 기준 상대 경로 (예: `src/cli.ts`)
+- `L<start>-L<end>`: 1-based 라인 범위 (예: `L36-L103`)
+- `hash8`: SHA-256 해시의 앞 8자 (도구가 자동 생성)
+
+### 예시
+````
+[[vctx:src/cli.ts#L36-L103@4db34b59]]
+[[vctx:src/verify/workspace.ts#L46-L109@39dad95f]]
+````
+
+### 검증 동작
+- 해당 파일의 지정 라인 범위를 읽어 SHA-256 해시를 재계산한다.
+- EOL 정규화 적용 (CRLF/CR → LF).
+- 해시가 일치하면 `ok: true`, 불일치하면 `hash_mismatch`.
+
+## Structure Claim (구조 선언)
+
+### 형식
+| Kind | 형식 | 의미 |
+|------|------|------|
+| `exists` | `[[vctx-exists:<path>]]` | 파일 또는 디렉토리가 존재 |
+| `exists-file` | `[[vctx-exists-file:<path>]]` | 파일로 존재 |
+| `exists-dir` | `[[vctx-exists-dir:<path>]]` | 디렉토리로 존재 |
+| `missing` | `[[vctx-missing:<path>]]` | 존재하지 않음 |
+
+### 예시
+````
+<!-- [[vctx-exists-dir:src/]] -->
+<!-- [[vctx-exists-file:package.json]] -->
+<!-- [[vctx-missing:tmp-output/]] -->
+````
+
+## 에러 코드
+
+| Reason | 원인 | 대응 |
+|--------|------|------|
+| `hash_mismatch` | 파일 내용 변경됨 | 재인용 (`vctx_cite`) |
+| `file_missing` | 파일 삭제/이동됨 | 문서 수정 또는 claim 제거 |
+| `range_invalid` | 라인 범위 초과 | 올바른 범위로 재인용 |
+| `path_escape` | `../` 등 루트 이탈 | 상대 경로 수정 |
+| `not_file` | 디렉토리인데 file claim | kind를 `exists-dir`로 변경 |
+| `not_dir` | 파일인데 dir claim | kind를 `exists-file`로 변경 |

package/skills/vericontext-enforcer/references/cross-agent-setup.md

@@ -0,0 +1,72 @@
+# VeriContext Cross-Agent Setup Guide
+
+## 사전 요구사항
+
+- Node.js >= 20
+- VeriContext CLI 설치:
+  ```bash
+  npm install   # (vericontext 프로젝트 내)
+  npm run build # dist/cli.js 생성
+  ```
+- 또는 글로벌 설치: `npm install -g vericontext`
+
+## Claude Code
+
+### MCP 서버 등록
+
+`~/.claude/settings.json` 또는 프로젝트 `.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "vericontext": {
+      "command": "node",
+      "args": ["<path-to>/dist/cli.js", "mcp"]
+    }
+  }
+}
+```
+
+### 스킬 자동 로드
+`.claude/skills/vericontext-enforcer` symlink가 있으면 자동으로 스킬이 로드된다.
+
+## Codex (OpenAI)
+
+### AGENTS.md 방식
+프로젝트 루트의 `AGENTS.md`에 다음을 추가한다:
+
+````markdown
+## DOCUMENT VERIFICATION
+이 프로젝트에서 문서를 작성/수정할 때:
+1. 코드를 참조하면 `vericontext cite --root . --path <file> --start-line <N> --end-line <M> --json`으로 citation을 생성한다.
+2. 파일/디렉토리 존재를 언급하면 `vericontext claim --root . --kind <kind> --path <path> --json`으로 claim을 생성한다.
+3. 커밋 전에 `vericontext verify workspace --root . --in-path <document.md> --json`을 실행하여 모든 claim이 유효한지 확인한다.
+4. `ok: false`이면 커밋하지 않고, 실패한 claim을 수정한 뒤 재검증한다.
+````
+
+## OpenCode
+
+### 커스텀 룰 또는 시스템 프롬프트
+Codex와 동일한 지침을 `.opencode/instructions.md` 또는 시스템 프롬프트에 추가한다.
+MCP를 지원하는 경우 Claude Code와 동일하게 MCP 서버를 등록한다.
+
+## Antigravity
+
+### INSTRUCTIONS.md 방식
+프로젝트 루트의 `INSTRUCTIONS.md`에 위의 AGENTS.md 내용과 동일한 지침을 추가한다.
+
+## CI/CD 게이팅 (선택)
+
+### GitHub Actions 예시
+```yaml
+- name: Verify documentation freshness
+  run: |
+    for doc in README.md AGENTS.md; do
+      result=$(npx vericontext verify workspace --root . --in-path "$doc" --json)
+      ok=$(echo "$result" | jq -r '.ok')
+      if [ "$ok" != "true" ]; then
+        echo "::error::Stale claims in $doc"
+        echo "$result" | jq '.results[] | select(.ok == false)'
+        exit 1
+      fi
+    done
+```

package/skills/vericontext-enforcer/references/verification-playbook.md

@@ -0,0 +1,79 @@
+# VeriContext Verification Playbook
+
+## 검증 실행
+
+### 단일 문서 검증
+```bash
+vericontext verify workspace --root . --in-path README.md --json
+```
+
+### 응답 구조
+```json
+{
+  "ok": true|false,
+  "total": <number>,
+  "ok_count": <number>,
+  "fail_count": <number>,
+  "results": [
+    {
+      "claim": "<full claim string>",
+      "ok": true|false,
+      "reason": "<error code if failed>"
+    }
+  ]
+}
+```
+
+## 실패 유형별 수정 절차
+
+### 1. `hash_mismatch` — 파일 내용이 변경됨
+
+```
+원인: citation이 가리키는 라인의 내용이 달라졌다.
+수정:
+  1. 해당 파일의 현재 내용을 확인한다.
+  2. 참조하려는 코드가 여전히 같은 위치에 있는지 확인한다.
+     - 같은 위치: vctx_cite를 다시 실행하여 새 hash로 교체.
+     - 다른 위치: 올바른 라인 범위를 찾아 재인용.
+     - 코드가 삭제됨: 문서에서 해당 참조를 제거하거나 수정.
+  3. 문서의 citation 토큰을 새 것으로 교체한다.
+```
+
+### 2. `file_missing` — 파일이 존재하지 않음
+
+```
+원인: 파일이 삭제되었거나 이름이 변경되었다.
+수정:
+  1. 파일이 이동/이름변경되었는지 확인한다.
+     - 이동됨: 새 경로로 citation 재생성.
+     - 삭제됨: 문서에서 해당 참조를 제거.
+  2. structure claim (exists-file 등)도 함께 수정한다.
+```
+
+### 3. `range_invalid` — 라인 범위 초과
+
+```
+원인: 파일이 줄어들어 지정한 end_line이 파일 길이를 초과한다.
+수정:
+  1. 파일의 현재 줄 수를 확인한다.
+  2. 참조하려는 코드의 현재 라인 범위를 찾는다.
+  3. 올바른 범위로 재인용한다.
+```
+
+### 4. `missing` / `not_file` / `not_dir` — structure claim 실패
+
+```
+원인: 파일/디렉토리가 예상과 다른 상태다.
+수정:
+  1. 실제 상태를 확인한다 (파일인지, 디렉토리인지, 없는지).
+  2. claim의 kind를 실제 상태에 맞게 수정하거나, 문서 내용을 수정한다.
+```
+
+## 수정 후 재검증
+
+수정을 마친 뒤 반드시 다시 검증을 실행한다:
+```bash
+vericontext verify workspace --root . --in-path <수정한문서.md> --json
+```
+
+`ok: true`가 될 때까지 반복한다. 검증 통과 전에는 커밋하지 않는다.

package/skills/vericontext-enforcer/scripts/verify-modified-docs.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# verify-docs.sh — VeriContext로 claim이 포함된 모든 프로젝트 문서를 검증
+# 코드만 변경돼도 citation hash가 깨질 수 있으므로, 문서 diff와 무관하게
+# claim이 포함된 모든 .md 파일을 검증한다.
+# 의존성: node >= 20, vericontext CLI (dist/cli.js)
+# 종료 코드: 0 = 모두 통과, 1 = 실패 있음
+
+set -euo pipefail
+
+ROOT="$(cd "${1:-.}" && pwd)"
+VCTX="${VERICONTEXT_BIN:-npx vericontext}"
+
+# claim 토큰([[vctx)이 포함된 .md 파일을 찾되,
+# 내부 도구/플랜/스킬 디렉토리는 제외한다.
+DOCS=$(grep -rl '\[\[vctx' "$ROOT" --include='*.md' \
+  | grep -v node_modules \
+  | grep -v '\.git/' \
+  | grep -v '\.agents/skills/' \
+  | grep -v '\.claude/skills/' \
+  | grep -v '\.sisyphus/' \
+  | sed "s|^$ROOT/||" \
+  | sort || true)
+
+if [ -z "$DOCS" ]; then
+  echo "[vericontext-enforcer] No documents with vctx claims found."
+  exit 0
+fi
+
+FAILED=0
+TOTAL=0
+
+while IFS= read -r doc; do
+  [ -z "$doc" ] && continue
+  TOTAL=$((TOTAL + 1))
+  echo "[vericontext-enforcer] Verifying: $doc"
+
+  RESULT=$($VCTX verify workspace --root "$ROOT" --in-path "$doc" --json 2>/dev/null || echo '{"ok":false,"error":"command_failed"}')
+  OK=$(echo "$RESULT" | grep -o '"ok":[a-z]*' | head -1 | cut -d: -f2)
+
+  if [ "$OK" = "true" ]; then
+    echo "  PASS"
+  else
+    echo "  FAIL"
+    echo "$RESULT" | python3 -m json.tool 2>/dev/null || echo "$RESULT"
+    FAILED=$((FAILED + 1))
+  fi
+done <<< "$DOCS"
+
+echo ""
+echo "[vericontext-enforcer] Results: $((TOTAL - FAILED))/$TOTAL passed"
+
+if [ "$FAILED" -gt 0 ]; then
+  echo "[vericontext-enforcer] $FAILED document(s) have stale claims. Fix before committing."
+  exit 1
+fi
+
+echo "[vericontext-enforcer] All documents verified."
+exit 0