obsidian-lean-coder 0.0.0-stage → 0.1.1

package/dist/session/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Session summary in plain language (OLC-063).
+ *
+ * Ends a normal session with a useful, non-technical summary in Indonesian,
+ * rendered through the `session-summary` template. Factual claims are mapped
+ * to real data only:
+ * - verification lines come from the caller's `VerifyOutcome` (never
+ *   invented — no outcome means "no tests ran");
+ * - the checkpoint line appears only when the caller passes the real
+ *   `checkpointSha` of this session;
+ * - open tasks / last events come from `buildResumeContext` (OLC-061).
+ *
+ * Durability: the full text is returned to the caller (the agent shows it),
+ * and a compact `session` event is appended to the activity log (OLC-060),
+ * so the next resume surfaces it. No separate summary file — that would
+ * need a new path convention for zero retrieval benefit.
+ *
+ * Honesty limit: this function only runs when the session ends normally. A
+ * hard kill produces no summary; the last log event is then the recovery
+ * point (see OLC-061). The rendered text says so in its footer.
+ */
+import type { ResolvedConfig } from "../config/index.js";
+import type { VerifyOutcome } from "../verify/index.js";
+export interface SessionSummaryInput {
+    /** Any directory inside the project (identity resolution starts here). */
+    projectRoot: string;
+    config: ResolvedConfig;
+    /** What was done, in plain words. Empty = no-code-change session. */
+    whatDone: string[];
+    /** Real test outcome when tests ran; omit when none ran. */
+    verifyOutcome?: VerifyOutcome;
+    /** Note shown when no tests ran (e.g. why). */
+    testsNote?: string;
+    /** Real checkpoint commit SHA created this session, if any. */
+    checkpointSha?: string;
+    /** Task the checkpoint belongs to, if any. */
+    checkpointTaskId?: string;
+    /** Why the session stopped without finishing (blocked scenario). */
+    blockedReason?: string;
+    /** Unfinished work, in plain words. */
+    remaining: string[];
+    /** Next step, in plain words. */
+    nextStep: string;
+    /** ISO timestamp; defaults to now. Inject a fixed value in tests. */
+    date?: string;
+}
+export interface SessionSummaryResult {
+    /** Full Indonesian summary (show this to the user). */
+    markdown: string;
+    /** Activity-log file the compact `session` event was appended to. */
+    logFile: string;
+    date: string;
+}
+export declare function buildSessionSummary(input: SessionSummaryInput): SessionSummaryResult;

package/dist/session/index.js

@@ -0,0 +1,108 @@
+/**
+ * Session summary in plain language (OLC-063).
+ *
+ * Ends a normal session with a useful, non-technical summary in Indonesian,
+ * rendered through the `session-summary` template. Factual claims are mapped
+ * to real data only:
+ * - verification lines come from the caller's `VerifyOutcome` (never
+ *   invented — no outcome means "no tests ran");
+ * - the checkpoint line appears only when the caller passes the real
+ *   `checkpointSha` of this session;
+ * - open tasks / last events come from `buildResumeContext` (OLC-061).
+ *
+ * Durability: the full text is returned to the caller (the agent shows it),
+ * and a compact `session` event is appended to the activity log (OLC-060),
+ * so the next resume surfaces it. No separate summary file — that would
+ * need a new path convention for zero retrieval benefit.
+ *
+ * Honesty limit: this function only runs when the session ends normally. A
+ * hard kill produces no summary; the last log event is then the recovery
+ * point (see OLC-061). The rendered text says so in its footer.
+ */
+import { logEvent } from "../log/index.js";
+import { buildResumeContext } from "../resume/index.js";
+import { renderTemplate } from "../vault/index.js";
+function bullets(items) {
+    return items.map((i) => `- ${i}`).join("\n");
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+export function buildSessionSummary(input) {
+    const iso = input.date ?? new Date().toISOString();
+    // Identity gate + real vault state (open tasks, recent events). Throws
+    // before anything is written when the vault is unavailable or mismatched.
+    const ctx = buildResumeContext({
+        projectRoot: input.projectRoot,
+        config: input.config,
+        lastEventsLimit: 10,
+    });
+    const whatDone = input.whatDone.length > 0
+        ? bullets(input.whatDone)
+        : "Tidak ada perubahan kode pada sesi ini.";
+    const resultLines = [];
+    if (input.verifyOutcome) {
+        const passed = input.verifyOutcome.results.filter((r) => r.ok).length;
+        const total = input.verifyOutcome.results.length;
+        resultLines.push(input.verifyOutcome.ok
+            ? `Verifikasi lolos: ${passed}/${total} pemeriksaan berhasil.`
+            : `Verifikasi belum lolos: ${passed}/${total} pemeriksaan berhasil. Perlu ditangani: ${input.verifyOutcome.escalated.join(", ") || "-"}.`);
+    }
+    else {
+        resultLines.push("Tidak ada verifikasi yang dijalankan pada sesi ini.");
+    }
+    if (input.checkpointSha) {
+        resultLines.push(`Checkpoint tersimpan pada commit ${input.checkpointSha}` +
+            (input.checkpointTaskId ? ` (task ${input.checkpointTaskId}).` : "."));
+    }
+    else {
+        resultLines.push("Tidak ada checkpoint baru pada sesi ini.");
+    }
+    if (input.blockedReason) {
+        resultLines.push(`Sesi terhenti: ${input.blockedReason}`);
+    }
+    const results = resultLines.join("\n");
+    const tests = input.verifyOutcome
+        ? [
+            ...input.verifyOutcome.results.map((r) => `- ${r.name}: ${r.ok ? "lolos" : "gagal"} (${r.attempts.length} percobaan)`),
+            ...(input.verifyOutcome.ok
+                ? []
+                : [`Perlu arahan pengguna: ${input.verifyOutcome.escalated.join(", ") || "-"}.`]),
+        ].join("\n")
+        : (input.testsNote ?? "Tidak ada test yang dijalankan pada sesi ini.");
+    const openLine = ctx.openTasks.length > 0
+        ? `Task terbuka: ${ctx.openTasks.map((t) => `${t.taskId} (${t.entry.status})`).join(", ")}.`
+        : "Tidak ada task terbuka.";
+    const remaining = [
+        ...(input.remaining.length > 0 ? [bullets(input.remaining)] : ["Tidak ada sisa pekerjaan yang tercatat."]),
+        openLine,
+        ...(input.blockedReason ? [`Penghalang: ${input.blockedReason}`] : []),
+    ].join("\n");
+    const markdown = renderTemplate("session-summary", {
+        project_id: input.config.projectId,
+        date: iso,
+        what_done: whatDone,
+        results,
+        tests,
+        remaining,
+        next_step: input.nextStep,
+    }) + "\nCatatan: ringkasan ini hanya dibuat bila sesi berakhir normal. Bila sesi mati mendadak, event terakhir di log adalah titik pemulihan.\n";
+    const headline = input.blockedReason
+        ? `terhenti: ${oneLine(input.blockedReason)}`
+        : input.checkpointSha
+            ? `selesai, checkpoint ${input.checkpointSha.slice(0, 7)}`
+            : "selesai tanpa checkpoint baru";
+    const { file } = logEvent({
+        projectRoot: input.projectRoot,
+        config: input.config,
+        event: {
+            kind: "session",
+            summary: `Ringkasan sesi: ${headline}.`,
+            details: `next: ${oneLine(input.nextStep)}`,
+            ...(input.checkpointSha ? { gitSha: input.checkpointSha } : {}),
+            ...(input.checkpointTaskId ? { taskId: input.checkpointTaskId } : {}),
+            date: iso,
+        },
+    });
+    return { markdown, logFile: file, date: iso };
+}

package/dist/tasks/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Task registry, branch matching, and status transitions (OLC-033).
+ *
+ * Stored at `tasks/registry.json` inside the project vault scope:
+ * `{ "tasks": { "<taskId>": { "status", "branch", "updatedAt" } } }`.
+ *
+ * Status transition table (also recorded in docs/DECISIONS.md #7):
+ *
+ * - draft      → approved, rejected
+ * - approved   → in_progress, draft
+ * - in_progress→ review, blocked
+ * - blocked    → in_progress
+ * - review     → done, in_progress
+ * - rejected   → draft
+ * - done       → (terminal; no outgoing transitions)
+ *
+ * Rules: a task reaches `done` only through an explicit `setTaskStatus`
+ * call after user confirmation — nothing transitions implicitly, and
+ * `in_progress` can never jump straight to `done` (must pass `review`).
+ * Resume only recommends; it never switches branches or tasks by itself.
+ */
+export type TaskStatus = "draft" | "approved" | "in_progress" | "review" | "blocked" | "rejected" | "done";
+export declare const TRANSITIONS: Record<TaskStatus, TaskStatus[]>;
+export declare const TERMINAL_STATUSES: TaskStatus[];
+export declare class TaskRegistryError extends Error {
+    readonly code: "INVALID_TRANSITION" | "ALREADY_REGISTERED" | "UNKNOWN_TASK" | "CORRUPT_REGISTRY";
+    constructor(code: "INVALID_TRANSITION" | "ALREADY_REGISTERED" | "UNKNOWN_TASK" | "CORRUPT_REGISTRY", message: string);
+}
+export interface TaskEntry {
+    status: TaskStatus;
+    branch: string | null;
+    updatedAt: string;
+}
+export interface TaskRegistry {
+    tasks: Record<string, TaskEntry>;
+}
+export declare function readRegistry(vaultRoot: string, projectId: string): TaskRegistry;
+/** Register a new task as `draft`. Duplicate ids are an error, never merged. */
+export declare function registerTask(vaultRoot: string, projectId: string, taskId: string, branch: string | null, date: string): TaskEntry;
+/** (Re)associate a task with a branch. Never switches the actual Git branch. */
+export declare function attachBranch(vaultRoot: string, projectId: string, taskId: string, branch: string | null, date: string): TaskEntry;
+/**
+ * Move a task to a new status. Only table-allowed transitions pass;
+ * anything else throws `INVALID_TRANSITION` listing what is allowed.
+ */
+export declare function setTaskStatus(vaultRoot: string, projectId: string, taskId: string, to: TaskStatus, date: string): TaskEntry;
+export declare function getTask(vaultRoot: string, projectId: string, taskId: string): TaskEntry | null;
+export interface ResumeRecommendation {
+    /** The recommended task, or null when there is nothing unambiguous to suggest. */
+    taskId: string | null;
+    /** Human-readable note: what was found and what confirmation is needed. */
+    note: string;
+}
+/**
+ * Recommend the most recently active non-terminal task on `currentBranch`.
+ * Recommendation only: never resumes, switches, or closes anything.
+ * Unknown/empty branch or no matching task yields a note asking the user.
+ */
+export declare function recommendResume(vaultRoot: string, projectId: string, currentBranch: string | null): ResumeRecommendation;

package/dist/tasks/index.js

@@ -0,0 +1,182 @@
+/**
+ * Task registry, branch matching, and status transitions (OLC-033).
+ *
+ * Stored at `tasks/registry.json` inside the project vault scope:
+ * `{ "tasks": { "<taskId>": { "status", "branch", "updatedAt" } } }`.
+ *
+ * Status transition table (also recorded in docs/DECISIONS.md #7):
+ *
+ * - draft      → approved, rejected
+ * - approved   → in_progress, draft
+ * - in_progress→ review, blocked
+ * - blocked    → in_progress
+ * - review     → done, in_progress
+ * - rejected   → draft
+ * - done       → (terminal; no outgoing transitions)
+ *
+ * Rules: a task reaches `done` only through an explicit `setTaskStatus`
+ * call after user confirmation — nothing transitions implicitly, and
+ * `in_progress` can never jump straight to `done` (must pass `review`).
+ * Resume only recommends; it never switches branches or tasks by itself.
+ */
+import { readVaultDoc, resolveVaultDoc, writeVaultDoc } from "../vault/index.js";
+export const TRANSITIONS = {
+    draft: ["approved", "rejected"],
+    approved: ["in_progress", "draft"],
+    in_progress: ["review", "blocked"],
+    blocked: ["in_progress"],
+    review: ["done", "in_progress"],
+    rejected: ["draft"],
+    done: [],
+};
+export const TERMINAL_STATUSES = ["done", "rejected"];
+export class TaskRegistryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "TaskRegistryError";
+        this.code = code;
+    }
+}
+const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-_]{0,63}$/;
+function registryPath(vaultRoot, projectId) {
+    return resolveVaultDoc(vaultRoot, projectId, "tasks", "registry.json");
+}
+function isTaskStatus(value) {
+    return (typeof value === "string" &&
+        Object.keys(TRANSITIONS).includes(value));
+}
+function parseRegistry(text, path) {
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (error) {
+        throw new TaskRegistryError("CORRUPT_REGISTRY", `Task registry at ${path} is not valid JSON (${error.message}). Fix or delete it to start fresh.`);
+    }
+    if (typeof json !== "object" || json === null || Array.isArray(json)) {
+        throw new TaskRegistryError("CORRUPT_REGISTRY", `Task registry at ${path} must be a JSON object with a "tasks" map.`);
+    }
+    const tasks = json["tasks"];
+    if (typeof tasks !== "object" || tasks === null || Array.isArray(tasks)) {
+        throw new TaskRegistryError("CORRUPT_REGISTRY", `Task registry at ${path} must contain a "tasks" object.`);
+    }
+    for (const [id, entry] of Object.entries(tasks)) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            throw new TaskRegistryError("CORRUPT_REGISTRY", `Task registry entry "${id}" must be an object.`);
+        }
+        const e = entry;
+        if (!isTaskStatus(e["status"])) {
+            throw new TaskRegistryError("CORRUPT_REGISTRY", `Task registry entry "${id}" has unknown status ${JSON.stringify(e["status"])}.`);
+        }
+        if (e["branch"] !== null && typeof e["branch"] !== "string") {
+            throw new TaskRegistryError("CORRUPT_REGISTRY", `Task registry entry "${id}" has a non-string branch.`);
+        }
+        if (typeof e["updatedAt"] !== "string") {
+            throw new TaskRegistryError("CORRUPT_REGISTRY", `Task registry entry "${id}" is missing string "updatedAt".`);
+        }
+    }
+    return { tasks: tasks };
+}
+export function readRegistry(vaultRoot, projectId) {
+    const path = registryPath(vaultRoot, projectId);
+    try {
+        return parseRegistry(readVaultDoc(path), path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { tasks: {} };
+        throw error;
+    }
+}
+function saveRegistry(vaultRoot, projectId, registry) {
+    writeVaultDoc(registryPath(vaultRoot, projectId), JSON.stringify(registry, null, 2) + "\n", {
+        overwrite: true,
+    });
+}
+function checkTaskId(taskId) {
+    if (!TASK_ID_PATTERN.test(taskId)) {
+        throw new TaskRegistryError("UNKNOWN_TASK", `Invalid task id ${JSON.stringify(taskId)}: use 1–64 letters, digits, dash or underscore.`);
+    }
+}
+/** Register a new task as `draft`. Duplicate ids are an error, never merged. */
+export function registerTask(vaultRoot, projectId, taskId, branch, date) {
+    checkTaskId(taskId);
+    const registry = readRegistry(vaultRoot, projectId);
+    if (registry.tasks[taskId]) {
+        throw new TaskRegistryError("ALREADY_REGISTERED", `Task ${taskId} is already registered (status ${registry.tasks[taskId].status}). Use setTaskStatus to move it.`);
+    }
+    const entry = { status: "draft", branch, updatedAt: date };
+    registry.tasks[taskId] = entry;
+    saveRegistry(vaultRoot, projectId, registry);
+    return entry;
+}
+/** (Re)associate a task with a branch. Never switches the actual Git branch. */
+export function attachBranch(vaultRoot, projectId, taskId, branch, date) {
+    const registry = readRegistry(vaultRoot, projectId);
+    const entry = registry.tasks[taskId];
+    if (!entry) {
+        throw new TaskRegistryError("UNKNOWN_TASK", `Task ${taskId} is not registered. Register it before attaching a branch.`);
+    }
+    entry.branch = branch;
+    entry.updatedAt = date;
+    saveRegistry(vaultRoot, projectId, registry);
+    return entry;
+}
+/**
+ * Move a task to a new status. Only table-allowed transitions pass;
+ * anything else throws `INVALID_TRANSITION` listing what is allowed.
+ */
+export function setTaskStatus(vaultRoot, projectId, taskId, to, date) {
+    const registry = readRegistry(vaultRoot, projectId);
+    const entry = registry.tasks[taskId];
+    if (!entry) {
+        throw new TaskRegistryError("UNKNOWN_TASK", `Task ${taskId} is not registered. Register it before changing status.`);
+    }
+    if (!TRANSITIONS[entry.status].includes(to)) {
+        const allowed = TRANSITIONS[entry.status];
+        throw new TaskRegistryError("INVALID_TRANSITION", `Task ${taskId} cannot move from ${entry.status} to ${to}. ` +
+            (allowed.length === 0
+                ? `${entry.status} is terminal — the task stays open as history.`
+                : `Allowed from ${entry.status}: ${allowed.join(", ")}.`));
+    }
+    entry.status = to;
+    entry.updatedAt = date;
+    saveRegistry(vaultRoot, projectId, registry);
+    return entry;
+}
+export function getTask(vaultRoot, projectId, taskId) {
+    return readRegistry(vaultRoot, projectId).tasks[taskId] ?? null;
+}
+/**
+ * Recommend the most recently active non-terminal task on `currentBranch`.
+ * Recommendation only: never resumes, switches, or closes anything.
+ * Unknown/empty branch or no matching task yields a note asking the user.
+ */
+export function recommendResume(vaultRoot, projectId, currentBranch) {
+    if (!currentBranch) {
+        return {
+            taskId: null,
+            note: "Current branch is unknown — tell me which branch and task to resume, and confirm before I continue.",
+        };
+    }
+    const registry = readRegistry(vaultRoot, projectId);
+    const onBranch = Object.entries(registry.tasks)
+        .filter(([, e]) => e.branch === currentBranch && !TERMINAL_STATUSES.includes(e.status))
+        .sort((a, b) => (a[1].updatedAt < b[1].updatedAt ? 1 : -1));
+    if (onBranch.length === 0) {
+        const total = Object.keys(registry.tasks).length;
+        return {
+            taskId: null,
+            note: total === 0
+                ? `No tasks are registered yet. Tell me which task to start on branch ${currentBranch}.`
+                : `No open tasks are attached to branch ${currentBranch} (${total} registered elsewhere). Tell me which task to resume, and confirm.`,
+        };
+    }
+    const [taskId, entry] = onBranch[0];
+    return {
+        taskId,
+        note: `Most recently active open task on ${currentBranch} is ${taskId} ` +
+            `(status ${entry.status}, updated ${entry.updatedAt}). Confirm before I resume it — nothing was switched or closed.`,
+    };
+}

package/dist/taste/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Taste proposal lifecycle (OLC-064).
+ *
+ * Project-specific preferences are learned without silently changing
+ * behavior: a repeated signal becomes a `pending` proposal carrying its
+ * examples/evidence, and only an explicit user approval flips it to
+ * `active`. Rejection parks it as `rejected` (history, never applied).
+ * Pending rules are never treated as active by any consumer.
+ *
+ * Scope guarantees:
+ * - Identity is validated first; wrong project or unavailable vault throws
+ *   before any read or write.
+ * - Every path resolves inside `<vault>/OLC/Projects/<projectId>/taste/`,
+ *   so other projects are untouched by construction.
+ * - This module only ever touches `taste/` — approved intent/plan docs
+ *   under `tasks/` cannot be overwritten from here.
+ * - Reuses the OLC-023 atomic create-only write: proposals never silently
+ *   replace an existing rule, and status flips require the rule to be
+ *   `pending` (terminal `active`/`rejected` states reject further review).
+ */
+import type { ResolvedConfig } from "../config/index.js";
+export type TasteStatus = "pending" | "active" | "rejected";
+export type TasteErrorCode = "INVALID_NAME" | "INVALID_INPUT" | "UNKNOWN_RULE" | "BAD_TRANSITION" | "ALREADY_EXISTS" | "CORRUPT_RULE";
+export declare class TasteError extends Error {
+    readonly code: TasteErrorCode;
+    constructor(code: TasteErrorCode, message: string);
+}
+export interface TasteRule {
+    name: string;
+    status: TasteStatus;
+    rule: string;
+    examples: string;
+}
+export interface ProposeTasteInput {
+    /** Any directory inside the project (identity resolution starts here). */
+    projectRoot: string;
+    config: ResolvedConfig;
+    /** Plain name (`no-any` → `taste/no-any.md`). No paths. */
+    name: string;
+    /** The proposed preference text. Must be non-empty. */
+    rule: string;
+    /**
+     * Observed repeat signals backing the proposal (corrections, accepts,
+     * rejects). At least one non-empty entry is required — a proposal
+     * without evidence is rejected outright.
+     */
+    examples: string[];
+}
+/**
+ * Record a repeat signal as a `pending` proposal. Never active on creation:
+ * activation needs a separate explicit `reviewTasteRule` approval.
+ * Throws before any write on invalid input or failed identity; an existing
+ * rule is never silently replaced.
+ */
+export declare function proposeTasteRule(input: ProposeTasteInput): TasteRule;
+/** Read one rule, or null when it does not exist. Identity is checked first. */
+export declare function getTasteRule(projectRoot: string, config: ResolvedConfig, name: string): TasteRule | null;
+export interface ListTasteInput {
+    projectRoot: string;
+    config: ResolvedConfig;
+    /** When set, only rules with this status are returned. */
+    status?: TasteStatus;
+}
+/** List rules in the validated project scope, sorted by name. Read-only. */
+export declare function listTasteRules(input: ListTasteInput): TasteRule[];
+export interface ReviewTasteInput {
+    /** Any directory inside the project (identity resolution starts here). */
+    projectRoot: string;
+    config: ResolvedConfig;
+    name: string;
+    /** True = user approves (pending→active); false = rejects (pending→rejected). */
+    approve: boolean;
+}
+/**
+ * Explicit user review of a `pending` proposal. Only pending rules move;
+ * active/rejected are terminal (re-review throws `BAD_TRANSITION`), and
+ * unknown names throw `UNKNOWN_RULE`. Nothing else in the vault is touched.
+ */
+export declare function reviewTasteRule(input: ReviewTasteInput): TasteRule;

package/dist/taste/index.js

@@ -0,0 +1,162 @@
+/**
+ * Taste proposal lifecycle (OLC-064).
+ *
+ * Project-specific preferences are learned without silently changing
+ * behavior: a repeated signal becomes a `pending` proposal carrying its
+ * examples/evidence, and only an explicit user approval flips it to
+ * `active`. Rejection parks it as `rejected` (history, never applied).
+ * Pending rules are never treated as active by any consumer.
+ *
+ * Scope guarantees:
+ * - Identity is validated first; wrong project or unavailable vault throws
+ *   before any read or write.
+ * - Every path resolves inside `<vault>/OLC/Projects/<projectId>/taste/`,
+ *   so other projects are untouched by construction.
+ * - This module only ever touches `taste/` — approved intent/plan docs
+ *   under `tasks/` cannot be overwritten from here.
+ * - Reuses the OLC-023 atomic create-only write: proposals never silently
+ *   replace an existing rule, and status flips require the rule to be
+ *   `pending` (terminal `active`/`rejected` states reject further review).
+ */
+import { readdirSync } from "node:fs";
+import { validateIdentity } from "../core/project-identity.js";
+import { parseFrontmatter, readVaultDoc, renderTemplate, resolveVaultDoc, writeVaultDoc, } from "../vault/index.js";
+export class TasteError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "TasteError";
+        this.code = code;
+    }
+}
+function checkName(name) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name)) {
+        throw new TasteError("INVALID_NAME", `Invalid taste rule name ${JSON.stringify(name)}: use letters, digits, dash or underscore, starting with a letter or digit. No paths, no extensions (".md" is added).`);
+    }
+}
+function readOrNull(path) {
+    try {
+        return readVaultDoc(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function listMdFiles(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isFile() && e.name.endsWith(".md"))
+            .map((e) => e.name)
+            .sort();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+const RULE_MARKER = "## Rule (aturan)";
+const EXAMPLES_MARKER = "## Examples / evidence";
+function parseTasteRule(name, text, path) {
+    const { data, body } = parseFrontmatter(text);
+    const status = data["status"];
+    if (status !== "pending" && status !== "active" && status !== "rejected") {
+        throw new TasteError("CORRUPT_RULE", `Taste rule at ${path} has unknown status ${JSON.stringify(status)}. Expected pending, active, or rejected — fix or delete the file.`);
+    }
+    const ruleAt = body.indexOf(RULE_MARKER);
+    const examplesAt = body.indexOf(EXAMPLES_MARKER);
+    if (ruleAt === -1 || examplesAt === -1 || examplesAt < ruleAt) {
+        throw new TasteError("CORRUPT_RULE", `Taste rule at ${path} does not follow the taste-rule template (missing Rule / Examples sections). Fix or delete the file.`);
+    }
+    return {
+        name,
+        status,
+        rule: body.slice(ruleAt + RULE_MARKER.length, examplesAt).trim(),
+        examples: body.slice(examplesAt + EXAMPLES_MARKER.length).trim(),
+    };
+}
+function rulePath(vaultRoot, projectId, name) {
+    return resolveVaultDoc(vaultRoot, projectId, "taste", `${name}.md`);
+}
+function renderRule(projectId, status, name, rule, examples) {
+    return renderTemplate("taste-rule", { project_id: projectId, status, name, rule, examples });
+}
+/**
+ * Record a repeat signal as a `pending` proposal. Never active on creation:
+ * activation needs a separate explicit `reviewTasteRule` approval.
+ * Throws before any write on invalid input or failed identity; an existing
+ * rule is never silently replaced.
+ */
+export function proposeTasteRule(input) {
+    checkName(input.name);
+    if (typeof input.rule !== "string" || input.rule.trim() === "") {
+        throw new TasteError("INVALID_INPUT", "Taste rule text must be a non-empty string.");
+    }
+    const examples = (input.examples ?? []).filter((e) => typeof e === "string" && e.trim() !== "");
+    if (examples.length === 0) {
+        throw new TasteError("INVALID_INPUT", "A taste proposal needs at least one example/evidence entry (the observed repeat signals).");
+    }
+    const identity = validateIdentity(input.projectRoot, input.config);
+    const path = rulePath(identity.vaultRoot, identity.projectId, input.name);
+    if (readOrNull(path) !== null) {
+        throw new TasteError("ALREADY_EXISTS", `Taste rule ${JSON.stringify(input.name)} already exists. Review or delete it explicitly — proposals are never merged silently.`);
+    }
+    const rule = {
+        name: input.name,
+        status: "pending",
+        rule: input.rule.trim(),
+        examples: examples.map((e) => `- ${e.trim()}`).join("\n"),
+    };
+    writeVaultDoc(path, renderRule(identity.projectId, "pending", rule.name, rule.rule, rule.examples));
+    return rule;
+}
+/** Read one rule, or null when it does not exist. Identity is checked first. */
+export function getTasteRule(projectRoot, config, name) {
+    checkName(name);
+    const identity = validateIdentity(projectRoot, config);
+    const path = rulePath(identity.vaultRoot, identity.projectId, name);
+    const text = readOrNull(path);
+    if (text === null)
+        return null;
+    return parseTasteRule(name, text, path);
+}
+/** List rules in the validated project scope, sorted by name. Read-only. */
+export function listTasteRules(input) {
+    const identity = validateIdentity(input.projectRoot, input.config);
+    const dir = resolveVaultDoc(identity.vaultRoot, identity.projectId, "taste");
+    const out = [];
+    for (const file of listMdFiles(dir)) {
+        const name = file.slice(0, -".md".length);
+        const path = rulePath(identity.vaultRoot, identity.projectId, name);
+        const text = readOrNull(path);
+        if (text === null)
+            continue;
+        const rule = parseTasteRule(name, text, path);
+        if (input.status === undefined || rule.status === input.status)
+            out.push(rule);
+    }
+    return out;
+}
+/**
+ * Explicit user review of a `pending` proposal. Only pending rules move;
+ * active/rejected are terminal (re-review throws `BAD_TRANSITION`), and
+ * unknown names throw `UNKNOWN_RULE`. Nothing else in the vault is touched.
+ */
+export function reviewTasteRule(input) {
+    checkName(input.name);
+    const identity = validateIdentity(input.projectRoot, input.config);
+    const path = rulePath(identity.vaultRoot, identity.projectId, input.name);
+    const text = readOrNull(path);
+    if (text === null) {
+        throw new TasteError("UNKNOWN_RULE", `Taste rule ${JSON.stringify(input.name)} does not exist. Propose it first.`);
+    }
+    const current = parseTasteRule(input.name, text, path);
+    if (current.status !== "pending") {
+        throw new TasteError("BAD_TRANSITION", `Taste rule ${JSON.stringify(input.name)} is already ${current.status} — only pending proposals can be reviewed.`);
+    }
+    const next = input.approve ? "active" : "rejected";
+    writeVaultDoc(path, renderRule(identity.projectId, next, current.name, current.rule, current.examples), { overwrite: true });
+    return { ...current, status: next };
+}