obsidian-lean-coder 0.0.0-stage → 0.1.1

package/dist/validation/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Session-start and pre-operation vault/project validation (OLC-065).
+ *
+ * Catches a missing/mismatched vault before OLC damages the wrong context.
+ * Lightweight by construction: every check reuses OLC-021 `validateIdentity`,
+ * which reads only git metadata (`rev-parse`) plus the single small
+ * `OLC/registry.json` file and a vault accessibility probe (`readdirSync`).
+ * The whole vault is never scanned.
+ *
+ * - `startSession` — call once at session start. Throws (IdentityError)
+ *   before anything is read or written when the repo, vault, or registration
+ *   is wrong.
+ * - `assertContextCurrent` — call before critical read/write/commit/restore
+ *   operations. Re-runs the same cheap gate (catches a vault unmounted or
+ *   a registry rewritten *between* operations) and additionally blocks on
+ *   drift: the repo root or branch no longer matches the session start
+ *   (branch switched mid-session), which always needs user confirmation.
+ *
+ * Identity problems propagate as `IdentityError` unchanged; drift is a
+ * `ValidationError(SESSION_DRIFT)`. Both block the operation with zero
+ * writes.
+ */
+import type { ResolvedConfig } from "../config/index.js";
+export type ValidationErrorCode = "SESSION_DRIFT";
+export declare class ValidationError extends Error {
+    readonly code: ValidationErrorCode;
+    constructor(code: ValidationErrorCode, message: string);
+}
+export interface SessionContext {
+    repoRoot: string;
+    branch: string;
+    projectId: string;
+    vaultRoot: string;
+    startedAt: string;
+}
+export interface SessionStartInput {
+    /** Any directory inside the project (identity resolution starts here). */
+    projectRoot: string;
+    config: ResolvedConfig;
+    /** Defaults to current time (pass explicit dates in tests). */
+    date?: string;
+}
+export interface RevalidateInput extends SessionStartInput {
+    /** Context captured by `startSession`; drift against it blocks. */
+    session: SessionContext;
+}
+/**
+ * Session-start gate. Returns the validated context to keep and pass to
+ * `assertContextCurrent` before later critical operations.
+ */
+export declare function startSession(input: SessionStartInput): SessionContext;
+/**
+ * Pre-operation revalidation. Re-runs the cheap identity gate (a vault
+ * unmounted, deleted, or re-registered between operations throws here,
+ * before the critical op touches anything) and blocks when the repo root
+ * or branch drifted since session start.
+ */
+export declare function assertContextCurrent(input: RevalidateInput): SessionContext;

package/dist/validation/index.js

@@ -0,0 +1,72 @@
+/**
+ * Session-start and pre-operation vault/project validation (OLC-065).
+ *
+ * Catches a missing/mismatched vault before OLC damages the wrong context.
+ * Lightweight by construction: every check reuses OLC-021 `validateIdentity`,
+ * which reads only git metadata (`rev-parse`) plus the single small
+ * `OLC/registry.json` file and a vault accessibility probe (`readdirSync`).
+ * The whole vault is never scanned.
+ *
+ * - `startSession` — call once at session start. Throws (IdentityError)
+ *   before anything is read or written when the repo, vault, or registration
+ *   is wrong.
+ * - `assertContextCurrent` — call before critical read/write/commit/restore
+ *   operations. Re-runs the same cheap gate (catches a vault unmounted or
+ *   a registry rewritten *between* operations) and additionally blocks on
+ *   drift: the repo root or branch no longer matches the session start
+ *   (branch switched mid-session), which always needs user confirmation.
+ *
+ * Identity problems propagate as `IdentityError` unchanged; drift is a
+ * `ValidationError(SESSION_DRIFT)`. Both block the operation with zero
+ * writes.
+ */
+import { resolve } from "node:path";
+import { validateIdentity } from "../core/project-identity.js";
+export class ValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ValidationError";
+        this.code = code;
+    }
+}
+/**
+ * Session-start gate. Returns the validated context to keep and pass to
+ * `assertContextCurrent` before later critical operations.
+ */
+export function startSession(input) {
+    const identity = validateIdentity(input.projectRoot, input.config);
+    return {
+        repoRoot: identity.repoRoot,
+        branch: identity.branch,
+        projectId: identity.projectId,
+        vaultRoot: identity.vaultRoot,
+        startedAt: input.date ?? new Date().toISOString(),
+    };
+}
+/**
+ * Pre-operation revalidation. Re-runs the cheap identity gate (a vault
+ * unmounted, deleted, or re-registered between operations throws here,
+ * before the critical op touches anything) and blocks when the repo root
+ * or branch drifted since session start.
+ */
+export function assertContextCurrent(input) {
+    const now = validateIdentity(input.projectRoot, input.config);
+    if (resolve(now.repoRoot) !== resolve(input.session.repoRoot)) {
+        throw new ValidationError("SESSION_DRIFT", `Refusing operation: repository root changed since session start ` +
+            `(was ${input.session.repoRoot}, now ${now.repoRoot}). ` +
+            "Confirm which checkout this work belongs to before continuing — nothing was read or written.");
+    }
+    if (now.branch !== input.session.branch) {
+        throw new ValidationError("SESSION_DRIFT", `Refusing operation: branch changed since session start ` +
+            `(was ${input.session.branch}, now ${now.branch}). ` +
+            "Confirm which branch and task this work belongs to before continuing — nothing was switched or closed.");
+    }
+    return {
+        repoRoot: now.repoRoot,
+        branch: now.branch,
+        projectId: now.projectId,
+        vaultRoot: now.vaultRoot,
+        startedAt: input.session.startedAt,
+    };
+}

package/dist/vault/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Markdown vault adapter (OLC-023).
+ *
+ * - `resolveVaultDoc`: safe path resolver — resolved paths must stay inside
+ *   the project's vault scope (`<vaultRoot>/OLC/Projects/<projectId>/`).
+ * - Minimal frontmatter convention: flat `key: value` scalars only.
+ * - `writeVaultDoc`: atomic (temp file + rename); refuses to replace an
+ *   existing document unless `overwrite: true` is passed explicitly.
+ * - `renderTemplate`: `{{variable}}` substitution over the package
+ *   `templates/` directory; missing variables are an error, never silent.
+ */
+export declare class VaultError extends Error {
+    readonly code: "PATH_ESCAPE" | "ALREADY_EXISTS" | "TEMPLATE_ERROR";
+    constructor(code: "PATH_ESCAPE" | "ALREADY_EXISTS" | "TEMPLATE_ERROR", message: string);
+}
+/** Vault scope root for one project, e.g. `<vault>/OLC/Projects/<id>`. */
+export declare function projectScopeRoot(vaultRoot: string, projectId: string): string;
+/**
+ * Resolve `...segments` inside the project's vault scope.
+ * Throws `VaultError(PATH_ESCAPE)` when the result would leave the scope.
+ */
+export declare function resolveVaultDoc(vaultRoot: string, projectId: string, ...segments: string[]): string;
+export interface FrontmatterDoc {
+    data: Record<string, string>;
+    body: string;
+}
+/** Parse `---\nkey: value\n---\nbody`. Flat string scalars only; no doc → empty data. */
+export declare function parseFrontmatter(text: string): FrontmatterDoc;
+/** Serialize flat string data + body with `---` fences. Values must be single-line. */
+export declare function withFrontmatter(data: Record<string, string>, body: string): string;
+export declare function readVaultDoc(path: string): string;
+export interface WriteOptions {
+    /** Must be true to replace an existing document. Default false (never silent). */
+    overwrite?: boolean;
+}
+/**
+ * Atomically write a UTF-8 vault document (temp file in the same directory
+ * + rename). Creates parent directories. Refuses to replace an existing file
+ * unless `overwrite: true`.
+ */
+export declare function writeVaultDoc(path: string, content: string, options?: WriteOptions): void;
+/** Locate the package `templates/` directory from the running module. */
+export declare function findTemplatesDir(): string;
+/**
+ * Render a `templates/<name>.md` template with `{{variable}}` substitution.
+ * Every placeholder must have a value; leftovers are an error.
+ */
+export declare function renderTemplate(name: string, vars: Record<string, string>): string;
+/** Template names shipped in `templates/` (one per OLC-023 work item). */
+export declare const BUNDLED_TEMPLATES: readonly ["intent", "plan", "explore-report", "checkpoint", "activity-log", "session-summary", "decision", "taste-rule"];

package/dist/vault/index.js

@@ -0,0 +1,153 @@
+/**
+ * Markdown vault adapter (OLC-023).
+ *
+ * - `resolveVaultDoc`: safe path resolver — resolved paths must stay inside
+ *   the project's vault scope (`<vaultRoot>/OLC/Projects/<projectId>/`).
+ * - Minimal frontmatter convention: flat `key: value` scalars only.
+ * - `writeVaultDoc`: atomic (temp file + rename); refuses to replace an
+ *   existing document unless `overwrite: true` is passed explicitly.
+ * - `renderTemplate`: `{{variable}}` substitution over the package
+ *   `templates/` directory; missing variables are an error, never silent.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+export class VaultError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "VaultError";
+        this.code = code;
+    }
+}
+/** Vault scope root for one project, e.g. `<vault>/OLC/Projects/<id>`. */
+export function projectScopeRoot(vaultRoot, projectId) {
+    return resolve(vaultRoot, "OLC", "Projects", projectId);
+}
+function checkSegment(segment) {
+    if (segment === "" ||
+        segment === "." ||
+        segment === ".." ||
+        isAbsolute(segment) ||
+        segment.includes("\0")) {
+        throw new VaultError("PATH_ESCAPE", `Refused vault path segment ${JSON.stringify(segment)}: ` +
+            "segments must be plain relative names, never absolute or parent references.");
+    }
+}
+/**
+ * Resolve `...segments` inside the project's vault scope.
+ * Throws `VaultError(PATH_ESCAPE)` when the result would leave the scope.
+ */
+export function resolveVaultDoc(vaultRoot, projectId, ...segments) {
+    const scope = projectScopeRoot(vaultRoot, projectId);
+    for (const segment of segments) {
+        for (const part of segment.split("/"))
+            checkSegment(part);
+    }
+    const resolved = resolve(scope, ...segments);
+    if (resolved !== scope && !resolved.startsWith(scope + sep)) {
+        throw new VaultError("PATH_ESCAPE", `Refused vault path ${JSON.stringify(segments.join("/"))}: resolves outside the project scope.`);
+    }
+    return resolved;
+}
+/** Parse `---\nkey: value\n---\nbody`. Flat string scalars only; no doc → empty data. */
+export function parseFrontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+    if (!match)
+        return { data: {}, body: text };
+    const data = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        if (line.trim() === "")
+            continue;
+        const colon = line.indexOf(":");
+        if (colon === -1)
+            continue;
+        data[line.slice(0, colon).trim()] = line.slice(colon + 1).trim();
+    }
+    return { data, body: match[2] };
+}
+/** Serialize flat string data + body with `---` fences. Values must be single-line. */
+export function withFrontmatter(data, body) {
+    for (const [key, value] of Object.entries(data)) {
+        if (!/^[A-Za-z0-9_-]+$/.test(key) || value.includes("\n")) {
+            throw new VaultError("TEMPLATE_ERROR", `Cannot serialize frontmatter key ${JSON.stringify(key)}: keys must be [A-Za-z0-9_-] and values single-line.`);
+        }
+    }
+    const head = Object.entries(data)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join("\n");
+    return `---\n${head}\n---\n${body}`;
+}
+export function readVaultDoc(path) {
+    return readFileSync(path, "utf8");
+}
+/**
+ * Atomically write a UTF-8 vault document (temp file in the same directory
+ * + rename). Creates parent directories. Refuses to replace an existing file
+ * unless `overwrite: true`.
+ */
+export function writeVaultDoc(path, content, options = {}) {
+    if (!options.overwrite && existsSync(path)) {
+        throw new VaultError("ALREADY_EXISTS", `Refused to overwrite existing vault document at ${path}: pass { overwrite: true } to replace it explicitly.`);
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = join(dirname(path), `.olc-tmp-${process.pid}-${Date.now()}`);
+    writeFileSync(tmp, content, "utf8");
+    renameSync(tmp, path);
+}
+/** Locate the package `templates/` directory from the running module. */
+export function findTemplatesDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const candidate of [
+        resolve(here, "..", "templates"),
+        resolve(here, "..", "..", "templates"),
+        resolve(here, "..", "..", "..", "templates"),
+    ]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new VaultError("TEMPLATE_ERROR", "Cannot locate the OLC templates/ directory relative to the running package. The installed package may be incomplete.");
+}
+/**
+ * Render a `templates/<name>.md` template with `{{variable}}` substitution.
+ * Every placeholder must have a value; leftovers are an error.
+ */
+export function renderTemplate(name, vars) {
+    if (name.includes("/") || name.includes("\\") || name.startsWith(".")) {
+        throw new VaultError("TEMPLATE_ERROR", `Refused template name ${JSON.stringify(name)}: plain file names only.`);
+    }
+    const path = join(findTemplatesDir(), `${name}.md`);
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        throw new VaultError("TEMPLATE_ERROR", `Template not found: ${name}.md.`);
+    }
+    const missing = new Set();
+    const rendered = text.replace(/\{\{\s*([A-Za-z0-9_-]+)\s*\}\}/g, (m, key) => {
+        if (!(key in vars)) {
+            missing.add(key);
+            return m;
+        }
+        return vars[key];
+    });
+    if (missing.size > 0) {
+        throw new VaultError("TEMPLATE_ERROR", `Template ${name}.md is missing values for: ${[...missing].join(", ")}.`);
+    }
+    if (/\{\{\s*[A-Za-z0-9_-]+\s*\}\}/.test(rendered)) {
+        throw new VaultError("TEMPLATE_ERROR", `Template ${name}.md has placeholders that accept no value (check for typos).`);
+    }
+    return rendered;
+}
+/** Template names shipped in `templates/` (one per OLC-023 work item). */
+export const BUNDLED_TEMPLATES = [
+    "intent",
+    "plan",
+    "explore-report",
+    "checkpoint",
+    "activity-log",
+    "session-summary",
+    "decision",
+    "taste-rule",
+];

package/dist/verify/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * OLC-041 — test/report/escalation behavior.
+ *
+ * Evidence-backed verification for one task frame:
+ * - `runCheck` executes a single command (no shell) and captures the real
+ *   outcome. Outcomes are NEVER invented: a spawn error, timeout, or
+ *   non-zero exit is recorded as-is and counts as failure.
+ * - `verifyChecks` re-runs failing checks up to `maxAttempts` (bounded
+ *   retry) and records EVERY attempt, so the report shows what actually ran.
+ * - `completeTaskWithVerification` runs the checks first and only delegates
+ *   to OLC-040 `completeTask` when all pass; otherwise it returns
+ *   `verify-failed` and leaves the registry untouched (caller stops and
+ *   reports — the escalation path). Scope/architecture changes still require
+ *   plan revision via OLC-034; this module never widens scope by itself.
+ */
+import { type BuildFrame } from "../build/index.js";
+import type { ResolvedConfig } from "../config/index.js";
+export interface CheckSpec {
+    /** Human-readable name shown in the report (e.g. "unit tests"). */
+    name: string;
+    /** Executable + args. Run directly with no shell. */
+    command: string[];
+    /** Per-attempt wall-clock budget. Default 120_000. */
+    timeoutMs?: number;
+}
+export interface CheckAttempt {
+    attempt: number;
+    /** Process exit code; null when the process never ran or was killed. */
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    /** Human-readable spawn failure (e.g. ENOENT). Absent on normal runs. */
+    error?: string;
+    durationMs: number;
+    ok: boolean;
+}
+export interface CheckResult {
+    name: string;
+    command: string[];
+    ok: boolean;
+    attempts: CheckAttempt[];
+}
+export interface VerifyOutcome {
+    ok: boolean;
+    results: CheckResult[];
+    /** Names of checks still failing after all attempts (the escalation list). */
+    escalated: string[];
+}
+/** Execute one check attempt. Never throws for check failures; only for programmer errors. */
+export declare function runCheck(spec: CheckSpec, cwd: string, attempt?: number): CheckAttempt;
+/**
+ * Run every check, retrying failures up to `maxAttempts` total attempts per
+ * check (bounded: `maxAttempts: 1` means no retry). Every attempt is kept.
+ */
+export declare function verifyChecks(specs: CheckSpec[], cwd: string, options?: {
+    maxAttempts?: number;
+}): VerifyOutcome;
+/** Render the outcome as Markdown (for history.md / session reports). */
+export declare function formatVerifyReport(outcome: VerifyOutcome): string;
+export type CompleteWithVerificationResult = {
+    verified: true;
+    changed: string[];
+} | {
+    verified: false;
+    status: "verify-failed";
+    outcome: VerifyOutcome;
+    report: string;
+};
+/**
+ * Verify first, complete only on pass. On failure the task registry is left
+ * untouched (still in_progress) and the caller must stop + report the
+ * outcome (escalation) instead of claiming success.
+ */
+export declare function completeTaskWithVerification(frame: BuildFrame, config: ResolvedConfig, repoRoot: string, checks: CheckSpec[], options?: {
+    maxAttempts?: number;
+    date?: string;
+}): CompleteWithVerificationResult;

package/dist/verify/index.js

@@ -0,0 +1,137 @@
+/**
+ * OLC-041 — test/report/escalation behavior.
+ *
+ * Evidence-backed verification for one task frame:
+ * - `runCheck` executes a single command (no shell) and captures the real
+ *   outcome. Outcomes are NEVER invented: a spawn error, timeout, or
+ *   non-zero exit is recorded as-is and counts as failure.
+ * - `verifyChecks` re-runs failing checks up to `maxAttempts` (bounded
+ *   retry) and records EVERY attempt, so the report shows what actually ran.
+ * - `completeTaskWithVerification` runs the checks first and only delegates
+ *   to OLC-040 `completeTask` when all pass; otherwise it returns
+ *   `verify-failed` and leaves the registry untouched (caller stops and
+ *   reports — the escalation path). Scope/architecture changes still require
+ *   plan revision via OLC-034; this module never widens scope by itself.
+ */
+import { spawnSync } from "node:child_process";
+import { completeTask } from "../build/index.js";
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_CHARS = 20_000;
+function clip(s) {
+    return s.length > MAX_OUTPUT_CHARS ? s.slice(0, MAX_OUTPUT_CHARS) + "\n…(truncated)" : s;
+}
+/** Execute one check attempt. Never throws for check failures; only for programmer errors. */
+export function runCheck(spec, cwd, attempt = 1) {
+    const started = Date.now();
+    const base = {
+        attempt,
+        exitCode: null,
+        stdout: "",
+        stderr: "",
+        timedOut: false,
+    };
+    let result;
+    try {
+        const [cmd, ...args] = spec.command;
+        if (!cmd) {
+            result = { ...base, error: "empty command" };
+        }
+        else {
+            const spawned = spawnSync(cmd, args, {
+                cwd,
+                timeout: spec.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+                encoding: "utf8",
+                maxBuffer: 10 * 1024 * 1024,
+                shell: false,
+            });
+            const err = spawned.error;
+            if (err) {
+                result = {
+                    ...base,
+                    stdout: clip(String(spawned.stdout ?? "")),
+                    stderr: clip(String(spawned.stderr ?? "")),
+                    timedOut: err.code === "ETIMEDOUT",
+                    error: `${err.code ?? err.name}: ${err.message}`,
+                };
+            }
+            else {
+                result = {
+                    ...base,
+                    exitCode: spawned.status,
+                    stdout: clip(String(spawned.stdout ?? "")),
+                    stderr: clip(String(spawned.stderr ?? "")),
+                };
+            }
+        }
+    }
+    catch (error) {
+        result = { ...base, error: `runner error: ${error.message}` };
+    }
+    const durationMs = Date.now() - started;
+    return { ...result, durationMs, ok: result.exitCode === 0 && !result.error };
+}
+/**
+ * Run every check, retrying failures up to `maxAttempts` total attempts per
+ * check (bounded: `maxAttempts: 1` means no retry). Every attempt is kept.
+ */
+export function verifyChecks(specs, cwd, options) {
+    const maxAttempts = Math.max(1, Math.floor(options?.maxAttempts ?? 1));
+    const results = specs.map((spec) => {
+        const attempts = [runCheck(spec, cwd, 1)];
+        while (!attempts[attempts.length - 1].ok && attempts.length < maxAttempts) {
+            attempts.push(runCheck(spec, cwd, attempts.length + 1));
+        }
+        return {
+            name: spec.name,
+            command: spec.command,
+            ok: attempts[attempts.length - 1].ok,
+            attempts,
+        };
+    });
+    return {
+        ok: results.every((r) => r.ok),
+        results,
+        escalated: results.filter((r) => !r.ok).map((r) => r.name),
+    };
+}
+/** Render the outcome as Markdown (for history.md / session reports). */
+export function formatVerifyReport(outcome) {
+    const lines = [
+        "## verification",
+        "",
+        `Result: ${outcome.ok ? "PASS" : "FAIL"} (${outcome.results.filter((r) => r.ok).length}/${outcome.results.length} checks passed)`,
+        "",
+    ];
+    for (const r of outcome.results) {
+        lines.push(`### ${r.name} — ${r.ok ? "PASS" : "FAIL"} (${r.attempts.length} attempt(s))`);
+        lines.push(`\`$ ${r.command.join(" ")}\``);
+        for (const a of r.attempts) {
+            lines.push(`- attempt ${a.attempt}: exit=${a.exitCode === null ? "n/a" : a.exitCode}` +
+                (a.timedOut ? " TIMED OUT" : "") +
+                (a.error ? ` error=${a.error}` : "") +
+                ` (${a.durationMs}ms)`);
+            if (a.stdout.trim() !== "")
+                lines.push(`  stdout: ${a.stdout.trim().split("\n").slice(-5).join(" | ")}`);
+            if (a.stderr.trim() !== "")
+                lines.push(`  stderr: ${a.stderr.trim().split("\n").slice(-5).join(" | ")}`);
+        }
+        lines.push("");
+    }
+    if (!outcome.ok) {
+        lines.push(`Escalated (needs user guidance, no auto-retry left): ${outcome.escalated.join(", ")}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Verify first, complete only on pass. On failure the task registry is left
+ * untouched (still in_progress) and the caller must stop + report the
+ * outcome (escalation) instead of claiming success.
+ */
+export function completeTaskWithVerification(frame, config, repoRoot, checks, options) {
+    const outcome = verifyChecks(checks, repoRoot, { maxAttempts: options?.maxAttempts });
+    if (!outcome.ok) {
+        return { verified: false, status: "verify-failed", outcome, report: formatVerifyReport(outcome) };
+    }
+    return { verified: true, ...completeTask(frame, config, repoRoot, options?.date) };
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "obsidian-lean-coder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Obsidian Lean Coder — OpenCode extension for project-scoped planning, memory, and safe Git checkpoints.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "agents",
+    "skills",
+    "templates",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.tests.json && node --test \"dist-tests/tests/**/*.test.js\"",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@opencode/plugin": "^2.0.27"
+  }
+}

package/skills/olc-explore/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: olc-explore
+description: Selidiki request yang kompleks/tidak pasti sebelum planning. Read-only terhadap app code; menghasilkan satu laporan eksplorasi di vault.
+---
+
+# olc-explore
+
+Klarifikasi request yang kompleks atau tidak pasti **sebelum** `intent.md`/`plan.md` dibuat.
+Untuk task sederhana yang sudah jelas, lewati skill ini dan langsung ke Plan (direct Plan).
+
+## Kapan dipakai vs direct Plan
+
+- Pakai Explore bila: request ambigu, menyentuh area yang belum dikenal, ada beberapa pendekatan dengan tradeoff nyata, atau risiko salah paham tinggi.
+- Direct Plan bila: perubahan kecil dan terlokalisasi, pendekatan sudah jelas, tidak ada pertanyaan material yang terbuka.
+- Pilihan user yang menang: kalau user minta direct Plan, jangan memaksa Explore, dan sebaliknya.
+
+## Aturan keras
+
+1. **Read-only terhadap app source.** Boleh membaca file, menjalankan perintah baca (status, log, test baca), menelusuri kode. DILARANG mengubah, menambah, atau menghapus file app dalam bentuk apa pun — tidak ada fix "sekalian", tidak ada refactor kecil.
+2. Satu laporan aktif per task: `tasks/<task-id>/explore/report.md` di vault proyek yang sudah tervalidasi (OLC-021). Jangan membuat file laporan tandingan.
+3. Setiap klaim temuan harus punya bukti: path file + baris, output perintah, atau kutipan config. Tanpa bukti = pertanyaan terbuka, bukan temuan.
+4. Revisi tidak menghapus penalaran penting: revisi ditambahkan sebagai bagian baru bertanggal di laporan yang sama; alasan perubahan pendekatan harus tercatat.
+
+## Alur
+
+1. Validasi identitas proyek dan baca `project_id` dari `.olc/config.json` (jangan operasi vault sebelum ini lolos).
+2. Baca request user + konteks relevan secukupnya (index/current-state vault bila ada, file app terkait). Jangan membaca seluruh vault.
+3. Tulis laporan via template `explore-report` (var: `task_id`, `project_id`, `date`, `request`, `findings`, `options`, `recommendation`). Buat direktori `explore/` bila belum ada; jangan menimpa laporan yang sudah dikustom tanpa persetujuan (ikuti aturan create-only OLC-023).
+4. Bila request berubah atau temuan baru muncul: tambah bagian revisi bertanggal di laporan yang sama, catat alasan di `history.md` task.
+5. Serahkan ke Plan: laporan explore adalah input `draftTaskDocs`, bukan pengganti `intent.md`/`plan.md`. Tanpa kedua dokumen itu disetujui, tidak ada coding (OLC-032).
+
+## Verifikasi skill ini
+
+- Setelah Explore: `git status --short` di repo app harus bersih (tidak ada perubahan app).
+- Laporan ada di path yang benar dan semua var template terisi (tidak ada `{{...}}` tersisa).

package/templates/activity-log.md

@@ -0,0 +1,10 @@
+---
+project: {{project_id}}
+date: {{date}}
+---
+
+# Activity log — {{date}}
+
+## {{event}} ({{timestamp}})
+
+{{details}}

package/templates/checkpoint.md

@@ -0,0 +1,24 @@
+---
+task: {{task_id}}
+project: {{project_id}}
+commit: {{commit_sha}}
+date: {{date}}
+---
+
+# Checkpoint — {{task_id}}
+
+## Commit
+
+{{commit_sha}}
+
+## Summary (ringkasan perubahan)
+
+{{summary}}
+
+## Verification results
+
+{{verification}}
+
+## Timestamp
+
+{{date}}