obsidian-lean-coder 0.0.0-stage → 0.1.0

package/dist/build/index.js

@@ -0,0 +1,146 @@
+/**
+ * OLC-040 — bounded `olc-build` task execution frame.
+ *
+ * The agent does the coding; this module enforces the bounds:
+ * 1. `beginTask` — identity (OLC-021, via the loaded OLC-020 config) and the
+ *    approval gate (OLC-034) must pass, otherwise implementation is blocked
+ *    before it starts. Returns a frame carrying ONLY the approved task's
+ *    context (intent/plan bodies), never the whole vault. The caller declares
+ *    which repo-relative paths it will touch; the registry task moves
+ *    approved→in_progress.
+ * 2. `recordDecision` — small in-scope technical decisions go to history.md.
+ * 3. `completeTask` — identity re-checked, then the working tree is diffed:
+ *    any change outside the declared paths throws SCOPE_CHANGED (out-of-scope
+ *    work is proposed via the error, not performed). Clean frames move the
+ *    registry task in_progress→review.
+ *
+ * Git access here is deliberately minimal (HEAD sha + porcelain status);
+ * the full inspection module is OLC-051's job and may consolidate these.
+ */
+import { execFileSync } from "node:child_process";
+import { assertBuildReady } from "../approval/index.js";
+import { validateIdentity } from "../core/project-identity.js";
+import { getTask, setTaskStatus } from "../tasks/index.js";
+import { readVaultDoc, resolveVaultDoc, writeVaultDoc } from "../vault/index.js";
+export class BuildError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = "BuildError";
+        this.code = code;
+        this.details = details;
+    }
+}
+function today(input) {
+    return input ?? new Date().toISOString().slice(0, 10);
+}
+function git(projectRoot, ...args) {
+    try {
+        // trimEnd only: porcelain's leading XY column may start with a space
+        // (e.g. " M file" for unstaged changes) and .trim() would eat it.
+        return execFileSync("git", args, { cwd: projectRoot, encoding: "utf8" }).replace(/\s+$/, "");
+    }
+    catch (error) {
+        throw new BuildError("CONTEXT_MISMATCH", `Build blocked: cannot inspect git state in ${projectRoot} (${error.message}).`);
+    }
+}
+function normalize(p) {
+    return p.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/** Repo-relative changed paths (staged + unstaged + untracked) vs current HEAD. */
+export function changedPaths(projectRoot) {
+    const out = git(projectRoot, "status", "--porcelain=v1", "-uall");
+    const paths = [];
+    for (const line of out.split("\n")) {
+        if (!line.trim())
+            continue;
+        let path = line.slice(3).trim();
+        const arrow = path.indexOf(" -> ");
+        if (arrow >= 0)
+            path = path.slice(arrow + 4);
+        if (path.startsWith('"') && path.endsWith('"'))
+            path = JSON.parse(path);
+        paths.push(normalize(path));
+    }
+    return paths;
+}
+function appendTaskHistory(vaultRoot, projectId, taskId, kind, reason, date) {
+    const history = resolveVaultDoc(vaultRoot, projectId, "tasks", taskId, "history.md");
+    let existing = "";
+    try {
+        existing = readVaultDoc(history);
+    }
+    catch {
+        existing = "";
+    }
+    const entry = `## ${date} — ${kind}\n\n${reason}\n`;
+    writeVaultDoc(history, existing === "" ? `# History — ${taskId}\n\n${entry}` : `${existing}\n${entry}`, { overwrite: true });
+}
+export function beginTask(input) {
+    const vaultRoot = input.config.vaultPath;
+    const projectId = input.config.projectId;
+    const startDir = input.startDir ?? process.cwd();
+    // Identity is checked from the caller's directory; the resolved repo root
+    // comes from git itself (OLC-021), never from config.
+    let repoRoot;
+    try {
+        repoRoot = git(startDir, "rev-parse", "--show-toplevel");
+    }
+    catch (error) {
+        throw new BuildError("CONTEXT_MISMATCH", `Build blocked: cannot determine repository root (${error.message}).`);
+    }
+    try {
+        validateIdentity(repoRoot, input.config);
+    }
+    catch (error) {
+        throw new BuildError("CONTEXT_MISMATCH", `Build blocked: ${error.message}`);
+    }
+    try {
+        assertBuildReady(vaultRoot, projectId, input.taskId);
+    }
+    catch (error) {
+        throw new BuildError("NOT_READY", `Build blocked: ${error.message}`);
+    }
+    const task = getTask(vaultRoot, projectId, input.taskId);
+    if (task === null) {
+        throw new BuildError("NO_TASK", `Build blocked: task "${input.taskId}" is not registered.`);
+    }
+    if (task.status === "approved") {
+        setTaskStatus(vaultRoot, projectId, input.taskId, "in_progress", today(input.date));
+    }
+    return {
+        taskId: input.taskId,
+        intentBody: readVaultDoc(resolveVaultDoc(vaultRoot, projectId, "tasks", input.taskId, "intent.md")),
+        planBody: readVaultDoc(resolveVaultDoc(vaultRoot, projectId, "tasks", input.taskId, "plan.md")),
+        declaredPaths: (input.touchPaths ?? []).map(normalize),
+        baseHead: git(repoRoot, "rev-parse", "HEAD"),
+        startedAt: new Date().toISOString(),
+    };
+}
+export function recordDecision(frame, config, text, date) {
+    if (!text.trim())
+        throw new BuildError("NO_TASK", "Decision text must be non-empty.");
+    appendTaskHistory(config.vaultPath, config.projectId, frame.taskId, "build-decision", text.trim(), today(date));
+}
+export function completeTask(frame, config, repoRoot, date) {
+    try {
+        validateIdentity(repoRoot, config);
+    }
+    catch (error) {
+        throw new BuildError("CONTEXT_MISMATCH", `Completion blocked: ${error.message}`);
+    }
+    const declared = new Set(frame.declaredPaths);
+    const changed = changedPaths(repoRoot);
+    const outOfScope = changed.filter((p) => !declared.has(p));
+    if (outOfScope.length > 0) {
+        throw new BuildError("SCOPE_CHANGED", `Completion blocked: ${outOfScope.length} changed path(s) outside the declared scope: ${outOfScope.join(", ")}. ` +
+            "Propose a plan revision instead — out-of-scope work is not completed silently.", outOfScope);
+    }
+    const task = getTask(config.vaultPath, config.projectId, frame.taskId);
+    if (task !== null && task.status === "in_progress") {
+        setTaskStatus(config.vaultPath, config.projectId, frame.taskId, "review", today(date));
+    }
+    appendTaskHistory(config.vaultPath, config.projectId, frame.taskId, "build-complete", `Build completed within declared scope (${changed.length} path(s)).`, today(date));
+    return { changed };
+}

package/dist/config/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * OLC project configuration (`.olc/config.json`).
+ *
+ * Minimal validated config per PRD §7.5 and OLC-020:
+ * - `schemaVersion` (currently 1; unknown future versions fail safely)
+ * - `projectId` (required; also used as the vault directory name)
+ * - `vaultPath` (optional in file; see precedence below)
+ *
+ * Vault-path precedence (highest first):
+ * 1. `OLC_VAULT_PATH` environment variable
+ * 2. `vaultPath` field in `.olc/config.json`
+ * 3. Neither → `ConfigError` (no silent default or fallback directory)
+ *
+ * Relative paths (env or file) resolve against the project root, never cwd,
+ * so results are deterministic regardless of where the process runs.
+ */
+export declare const CONFIG_SCHEMA_VERSION = 1;
+export declare const CONFIG_REL_PATH = ".olc/config.json";
+export declare const VAULT_PATH_ENV = "OLC_VAULT_PATH";
+export type ConfigErrorCode = "MISSING_CONFIG" | "UNREADABLE_CONFIG" | "INVALID_JSON" | "INVALID_CONFIG" | "UNSUPPORTED_SCHEMA" | "SECRET_IN_CONFIG" | "MISSING_VAULT_PATH";
+export declare class ConfigError extends Error {
+    readonly code: ConfigErrorCode;
+    constructor(code: ConfigErrorCode, message: string);
+}
+export interface OlcConfig {
+    schemaVersion: number;
+    projectId: string;
+    vaultPath?: string;
+}
+export interface ResolvedConfig extends OlcConfig {
+    /** Absolute vault path after applying precedence rules. Always present. */
+    vaultPath: string;
+}
+/**
+ * Validate unknown parsed JSON into an `OlcConfig`. Pure (no I/O).
+ * Throws `ConfigError` with an actionable message on any problem.
+ */
+export declare function parseConfig(json: unknown): OlcConfig;
+/**
+ * Read and validate `.olc/config.json` under `projectRoot`.
+ * Returns `null` when the file does not exist (missing ≠ invalid;
+ * callers such as init decide what missing means). Throws `ConfigError`
+ * when the file exists but cannot be read or parsed.
+ */
+export declare function readConfigFile(projectRoot: string): OlcConfig | null;
+/**
+ * Resolve the vault path applying precedence: env > config file > error.
+ * Returns an absolute path (relative inputs resolve against `projectRoot`).
+ */
+export declare function resolveVaultPath(config: OlcConfig, projectRoot: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Load `.olc/config.json` under `projectRoot` and resolve the vault path.
+ * Throws `ConfigError` when the file is missing, invalid, or no vault path
+ * is configured from either source.
+ */
+export declare function loadConfig(projectRoot: string, env?: NodeJS.ProcessEnv): ResolvedConfig;

package/dist/config/index.js

@@ -0,0 +1,136 @@
+/**
+ * OLC project configuration (`.olc/config.json`).
+ *
+ * Minimal validated config per PRD §7.5 and OLC-020:
+ * - `schemaVersion` (currently 1; unknown future versions fail safely)
+ * - `projectId` (required; also used as the vault directory name)
+ * - `vaultPath` (optional in file; see precedence below)
+ *
+ * Vault-path precedence (highest first):
+ * 1. `OLC_VAULT_PATH` environment variable
+ * 2. `vaultPath` field in `.olc/config.json`
+ * 3. Neither → `ConfigError` (no silent default or fallback directory)
+ *
+ * Relative paths (env or file) resolve against the project root, never cwd,
+ * so results are deterministic regardless of where the process runs.
+ */
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+export const CONFIG_SCHEMA_VERSION = 1;
+export const CONFIG_REL_PATH = ".olc/config.json";
+export const VAULT_PATH_ENV = "OLC_VAULT_PATH";
+/** Safe as a single vault directory name: no separators, no leading dots. */
+const PROJECT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-_]{0,63}$/;
+/** Top-level keys that look like credentials are rejected (PRD: no secrets in config). */
+const SECRET_KEY_PATTERN = /secret|token|password|passwd|api[-_]?key/i;
+export class ConfigError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ConfigError";
+        this.code = code;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Validate unknown parsed JSON into an `OlcConfig`. Pure (no I/O).
+ * Throws `ConfigError` with an actionable message on any problem.
+ */
+export function parseConfig(json) {
+    if (!isRecord(json)) {
+        throw new ConfigError("INVALID_CONFIG", "Invalid OLC config: expected a JSON object at the top level. " +
+            `Fix ${CONFIG_REL_PATH} or re-run init to regenerate it.`);
+    }
+    for (const key of Object.keys(json)) {
+        if (SECRET_KEY_PATTERN.test(key)) {
+            throw new ConfigError("SECRET_IN_CONFIG", `Invalid OLC config: key "${key}" looks like a credential. ` +
+                "Do not store secrets in .olc/config.json — remove the key and use your shell or secret manager instead.");
+        }
+    }
+    const allowed = new Set(["schemaVersion", "projectId", "vaultPath"]);
+    const unknownKeys = Object.keys(json).filter((k) => !allowed.has(k));
+    if (unknownKeys.length > 0) {
+        throw new ConfigError("INVALID_CONFIG", `Invalid OLC config: unknown key(s) ${unknownKeys.map((k) => `"${k}"`).join(", ")}. ` +
+            `Allowed keys are "schemaVersion", "projectId", "vaultPath". Fix ${CONFIG_REL_PATH}.`);
+    }
+    const { schemaVersion, projectId, vaultPath } = json;
+    if (typeof schemaVersion !== "number" || !Number.isInteger(schemaVersion)) {
+        throw new ConfigError("INVALID_CONFIG", 'Invalid OLC config: "schemaVersion" must be an integer. ' +
+            `Fix ${CONFIG_REL_PATH} (expected ${CONFIG_SCHEMA_VERSION}).`);
+    }
+    if (schemaVersion !== CONFIG_SCHEMA_VERSION) {
+        throw new ConfigError("UNSUPPORTED_SCHEMA", `Unsupported OLC config schema version ${schemaVersion} (this OLC supports ${CONFIG_SCHEMA_VERSION}). ` +
+            "Upgrade OLC to a version that understands this config, or regenerate the config with init.");
+    }
+    if (typeof projectId !== "string" || projectId.trim() === "") {
+        throw new ConfigError("INVALID_CONFIG", 'Invalid OLC config: "projectId" must be a non-empty string. ' +
+            `Fix ${CONFIG_REL_PATH} (it becomes the vault directory name).`);
+    }
+    if (!PROJECT_ID_PATTERN.test(projectId)) {
+        throw new ConfigError("INVALID_CONFIG", `Invalid OLC config: "projectId" ${JSON.stringify(projectId)} is not allowed. ` +
+            "Use 1–64 characters of letters, digits, dash or underscore, starting with a letter or digit " +
+            `(it becomes a vault directory name, so separators and dots are forbidden). Fix ${CONFIG_REL_PATH}.`);
+    }
+    if (vaultPath !== undefined && (typeof vaultPath !== "string" || vaultPath.trim() === "")) {
+        throw new ConfigError("INVALID_CONFIG", 'Invalid OLC config: "vaultPath" must be a non-empty string when present. ' +
+            `Remove it or set a real path in ${CONFIG_REL_PATH}.`);
+    }
+    const config = { schemaVersion, projectId };
+    if (typeof vaultPath === "string")
+        config.vaultPath = vaultPath;
+    return config;
+}
+/**
+ * Read and validate `.olc/config.json` under `projectRoot`.
+ * Returns `null` when the file does not exist (missing ≠ invalid;
+ * callers such as init decide what missing means). Throws `ConfigError`
+ * when the file exists but cannot be read or parsed.
+ */
+export function readConfigFile(projectRoot) {
+    const path = resolve(projectRoot, CONFIG_REL_PATH);
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw new ConfigError("UNREADABLE_CONFIG", `Cannot read OLC config at ${path}: ${error.message}. Check file permissions.`);
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (error) {
+        throw new ConfigError("INVALID_JSON", `Invalid OLC config: ${path} is not valid JSON (${error.message}). Fix the file or re-run init.`);
+    }
+    return parseConfig(json);
+}
+/**
+ * Resolve the vault path applying precedence: env > config file > error.
+ * Returns an absolute path (relative inputs resolve against `projectRoot`).
+ */
+export function resolveVaultPath(config, projectRoot, env = process.env) {
+    const fromEnv = env[VAULT_PATH_ENV]?.trim();
+    const raw = fromEnv ? fromEnv : config.vaultPath?.trim();
+    if (!raw) {
+        throw new ConfigError("MISSING_VAULT_PATH", `No vault path configured: set the ${VAULT_PATH_ENV} environment variable ` +
+            `or add "vaultPath" to ${CONFIG_REL_PATH}. OLC never invents a vault location.`);
+    }
+    return isAbsolute(raw) ? raw : resolve(projectRoot, raw);
+}
+/**
+ * Load `.olc/config.json` under `projectRoot` and resolve the vault path.
+ * Throws `ConfigError` when the file is missing, invalid, or no vault path
+ * is configured from either source.
+ */
+export function loadConfig(projectRoot, env = process.env) {
+    const path = resolve(projectRoot, CONFIG_REL_PATH);
+    const config = readConfigFile(projectRoot);
+    if (config === null) {
+        throw new ConfigError("MISSING_CONFIG", `No OLC config found at ${path}. Run init to create one (it asks for project_id and vault path).`);
+    }
+    return { ...config, vaultPath: resolveVaultPath(config, projectRoot, env) };
+}

package/dist/core/project-identity.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Project and vault identity checks (OLC-021, PRD §7.5 items 1–5 subset).
+ *
+ * Before any OLC-dependent operation, `validateIdentity` proves:
+ * 1. The working directory is inside a git repository (`resolveRepoRoot`).
+ * 2. The repository has an active branch (`resolveBranch`).
+ * 3. The vault root exists and is accessible (no fallback storage is created).
+ * 4. The vault registry (`OLC/registry.json`) exists, parses, and contains
+ *    this config's `projectId` mapped to THIS repository root.
+ *
+ * Any failure throws `IdentityError` with an actionable message. The caller
+ * must block the operation — never work around a failed check.
+ */
+import type { ResolvedConfig } from "../config/index.js";
+/** Vault registry location, relative to the vault root. */
+export declare const REGISTRY_REL_PATH = "OLC/registry.json";
+export type IdentityErrorCode = "NOT_A_REPO" | "GIT_FAILED" | "DETACHED_HEAD" | "VAULT_UNAVAILABLE" | "MISSING_REGISTRY" | "INVALID_REGISTRY" | "UNREGISTERED_PROJECT" | "PROJECT_MISMATCH";
+export declare class IdentityError extends Error {
+    readonly code: IdentityErrorCode;
+    constructor(code: IdentityErrorCode, message: string);
+}
+export interface ProjectIdentity {
+    repoRoot: string;
+    branch: string;
+    projectId: string;
+    vaultRoot: string;
+}
+/**
+ * Walk up from `startDir` to find the repository root (directory holding
+ * `.git`, which may be a dir or a worktree pointer file). Throws NOT_A_REPO.
+ */
+export declare function resolveRepoRoot(startDir: string): string;
+/**
+ * Current branch of the repository. Throws DETACHED_HEAD when HEAD is
+ * detached (identity needs an explicit branch) and GIT_FAILED when the
+ * branch cannot be determined (e.g. unborn HEAD with no commits yet).
+ */
+export declare function resolveBranch(repoRoot: string): string;
+/** Registry shape: project_id -> repository root that owns it. */
+export interface VaultRegistry {
+    projects: Record<string, {
+        repoRoot: string;
+    }>;
+}
+/** Throw VAULT_UNAVAILABLE unless `vaultRoot` exists and is a readable directory. */
+export declare function assertVaultAccessible(vaultRoot: string): void;
+/** Read and validate the vault registry. Throws MISSING_REGISTRY / INVALID_REGISTRY. */
+export declare function readRegistry(vaultRoot: string): VaultRegistry;
+/**
+ * Full identity gate. `startDir` is any directory inside the project
+ * (usually cwd); `config` is the loaded + vault-resolved OLC config.
+ */
+export declare function validateIdentity(startDir: string, config: ResolvedConfig): ProjectIdentity;

package/dist/core/project-identity.js

@@ -0,0 +1,141 @@
+/**
+ * Project and vault identity checks (OLC-021, PRD §7.5 items 1–5 subset).
+ *
+ * Before any OLC-dependent operation, `validateIdentity` proves:
+ * 1. The working directory is inside a git repository (`resolveRepoRoot`).
+ * 2. The repository has an active branch (`resolveBranch`).
+ * 3. The vault root exists and is accessible (no fallback storage is created).
+ * 4. The vault registry (`OLC/registry.json`) exists, parses, and contains
+ *    this config's `projectId` mapped to THIS repository root.
+ *
+ * Any failure throws `IdentityError` with an actionable message. The caller
+ * must block the operation — never work around a failed check.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+/** Vault registry location, relative to the vault root. */
+export const REGISTRY_REL_PATH = "OLC/registry.json";
+export class IdentityError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "IdentityError";
+        this.code = code;
+    }
+}
+/**
+ * Walk up from `startDir` to find the repository root (directory holding
+ * `.git`, which may be a dir or a worktree pointer file). Throws NOT_A_REPO.
+ */
+export function resolveRepoRoot(startDir) {
+    let dir = resolve(startDir);
+    for (;;) {
+        if (existsSync(resolve(dir, ".git")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new IdentityError("NOT_A_REPO", `Not a git repository: no .git found from ${resolve(startDir)} up to the filesystem root. ` +
+                "Run OLC inside a git repository (checkpoints and identity need one).");
+        }
+        dir = parent;
+    }
+}
+/** Run a git command, converting any failure into an IdentityError. */
+function git(args, cwd) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    }
+    catch (error) {
+        const detail = error.stderr ?? error.message;
+        throw new IdentityError("GIT_FAILED", `git ${args.join(" ")} failed in ${cwd}: ${String(detail).trim()}. Is git installed and the repository intact?`);
+    }
+}
+/**
+ * Current branch of the repository. Throws DETACHED_HEAD when HEAD is
+ * detached (identity needs an explicit branch) and GIT_FAILED when the
+ * branch cannot be determined (e.g. unborn HEAD with no commits yet).
+ */
+export function resolveBranch(repoRoot) {
+    const name = git(["rev-parse", "--abbrev-ref", "HEAD"], repoRoot);
+    if (name === "HEAD") {
+        const sha = git(["rev-parse", "HEAD"], repoRoot);
+        throw new IdentityError("DETACHED_HEAD", `Repository at ${repoRoot} has a detached HEAD (${sha}). ` +
+            "Check out a branch before running OLC so checkpoints land somewhere traceable.");
+    }
+    return name;
+}
+function isRegistry(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const projects = value.projects;
+    if (typeof projects !== "object" || projects === null || Array.isArray(projects))
+        return false;
+    return Object.values(projects).every((entry) => typeof entry === "object" && entry !== null && typeof entry.repoRoot === "string");
+}
+/** Throw VAULT_UNAVAILABLE unless `vaultRoot` exists and is a readable directory. */
+export function assertVaultAccessible(vaultRoot) {
+    try {
+        readdirSync(vaultRoot);
+    }
+    catch (error) {
+        const err = error;
+        const reason = err.code === "ENOENT"
+            ? "it does not exist"
+            : err.code === "EACCES" || err.code === "EPERM"
+                ? "permission denied"
+                : (err.message ?? "it is not accessible");
+        throw new IdentityError("VAULT_UNAVAILABLE", `Vault at ${vaultRoot} is unavailable (${reason}). ` +
+            "Check the path (OLC_VAULT_PATH or vaultPath) and permissions. OLC never creates fallback storage.");
+    }
+}
+/** Read and validate the vault registry. Throws MISSING_REGISTRY / INVALID_REGISTRY. */
+export function readRegistry(vaultRoot) {
+    const path = resolve(vaultRoot, REGISTRY_REL_PATH);
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new IdentityError("MISSING_REGISTRY", `No vault registry at ${path}. Run init to register this project in the vault.`);
+        }
+        throw new IdentityError("VAULT_UNAVAILABLE", `Cannot read vault registry at ${path}: ${error.message}. Check permissions.`);
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (error) {
+        throw new IdentityError("INVALID_REGISTRY", `Vault registry at ${path} is not valid JSON (${error.message}). Fix it or re-run init.`);
+    }
+    if (!isRegistry(json)) {
+        throw new IdentityError("INVALID_REGISTRY", `Vault registry at ${path} has the wrong shape. Expected {"projects": {"<project_id>": {"repoRoot": "<abs path>"}}}. Fix it or re-run init.`);
+    }
+    return json;
+}
+/**
+ * Full identity gate. `startDir` is any directory inside the project
+ * (usually cwd); `config` is the loaded + vault-resolved OLC config.
+ */
+export function validateIdentity(startDir, config) {
+    const repoRoot = resolveRepoRoot(startDir);
+    const branch = resolveBranch(repoRoot);
+    const vaultRoot = config.vaultPath;
+    if (!isAbsolute(vaultRoot)) {
+        throw new IdentityError("VAULT_UNAVAILABLE", `Resolved vault path ${JSON.stringify(vaultRoot)} is not absolute. This is an OLC bug — report it.`);
+    }
+    assertVaultAccessible(vaultRoot);
+    const registry = readRegistry(vaultRoot);
+    const entry = registry.projects[config.projectId];
+    if (!entry) {
+        throw new IdentityError("UNREGISTERED_PROJECT", `project_id "${config.projectId}" is not registered in vault ${vaultRoot}. ` +
+            "Run init to register it before using project memory, plans, or checkpoints.");
+    }
+    if (resolve(entry.repoRoot) !== repoRoot) {
+        throw new IdentityError("PROJECT_MISMATCH", `project_id "${config.projectId}" is registered to a different repository ` +
+            `(${resolve(entry.repoRoot)}) than the one you are in (${repoRoot}). ` +
+            "Refusing to touch the wrong project's memory. Use init with a new project_id for this checkout, or move to the registered repository.");
+    }
+    return { repoRoot, branch, projectId: config.projectId, vaultRoot };
+}

package/dist/git/checkpoint.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Safe Git checkpoint commits (OLC-051, enforces the OLC-050 decision).
+ *
+ * Flow: validate identity → normalize owned paths → refuse when an owned
+ * path is already staged → byte-compare every owned file against the
+ * caller-supplied write-time snapshot (any difference = someone else
+ * touched it → abort, zero git mutation) → `git add -- <owned paths>` →
+ * re-verify staged bytes against the snapshots (race guard; reset ours on
+ * mismatch) → `git commit -- <owned paths>` (pathspec, so foreign staged
+ * changes on other paths survive untouched) → append the checkpoint record
+ * (with commit SHA) to `tasks/<taskId>/checkpoint.md` in the vault.
+ *
+ * Banned from this flow, always: `git add .` / `git add -A`, plain
+ * `git commit` without a pathspec, and `git add -p`.
+ *
+ * MVP limits: owned paths must currently exist as files (file deletions by
+ * OLC are not checkpointable yet); snapshots are UTF-8 strings.
+ */
+import type { ResolvedConfig } from "../config/index.js";
+import { type SessionContext } from "../validation/index.js";
+export type CheckpointErrorCode = "PATH_OUTSIDE_REPO" | "OWNED_PATH_PRESTAGED" | "FOREIGN_EDIT" | "MISSING_OWNED_FILE";
+export declare class CheckpointError extends Error {
+    readonly code: CheckpointErrorCode;
+    constructor(code: CheckpointErrorCode, message: string);
+}
+export interface CheckpointInput {
+    /** Any directory inside the project (identity resolution starts here). */
+    projectRoot: string;
+    config: ResolvedConfig;
+    taskId: string;
+    /** Repo-relative paths OLC owns for this checkpoint (files must exist). */
+    ownedPaths: string[];
+    /** Write-time content snapshot per repo-relative owned path. */
+    snapshots: Record<string, string>;
+    summary: string;
+    verification?: string;
+    /** Defaults to current time (pass explicit dates in tests). */
+    date?: string;
+    /**
+     * Session context from `startSession`. When present the commit is also
+     * revalidated against it (vault unmounted / re-registered / branch
+     * switched between operations blocks with zero writes).
+     */
+    session?: SessionContext;
+}
+export type CheckpointResult = {
+    status: "clean";
+    branch: string;
+    head: string;
+} | {
+    status: "committed";
+    branch: string;
+    sha: string;
+    committedPaths: string[];
+    recordPath: string;
+};
+/**
+ * Append a checkpoint-template entry to `tasks/<taskId>/checkpoint.md`.
+ * First call writes the full template; later calls append the body after `---`.
+ * Returns the vault-absolute record path. Exported for reuse by `restore.ts`.
+ */
+export declare function appendCheckpointRecord(vaultRoot: string, projectId: string, taskId: string, vars: Record<string, string>): string;
+export declare function createCheckpoint(input: CheckpointInput): CheckpointResult;