obsidian-lean-coder 0.0.0-stage → 0.1.1

package/dist/memory/index.js

@@ -0,0 +1,166 @@
+/**
+ * Progressive memory retrieval (OLC-062).
+ *
+ * Read the small things first (`index.md`, `current-state.md`), then pull
+ * only the memory/decision docs, task docs, and log events relevant to the
+ * caller's query. Never scans the whole vault: every read is resolved inside
+ * the validated project's scope, so unrelated project folders are untouched
+ * by construction. Writes (`recordMemory`) go through the same identity gate
+ * and land only inside the validated project scope.
+ *
+ * Reuses: identity gate (OLC-021), scope-enforced vault paths + atomic
+ * writes (OLC-023), newest-first log readers (OLC-060).
+ */
+import { readdirSync } from "node:fs";
+import { validateIdentity } from "../core/project-identity.js";
+import { readLastEvents } from "../log/index.js";
+import { readVaultDoc, resolveVaultDoc, writeVaultDoc, } from "../vault/index.js";
+export class MemoryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "MemoryError";
+        this.code = code;
+    }
+}
+/** Directories searched for relevant docs — always inside one project scope. */
+const SEARCH_DIRS = ["memory", "decisions"];
+/** Tokens this short or this common never match (noise guard for scoring). */
+const STOPWORDS = new Set("a,an,the,and,or,for,with,that,this,from,are,was,were,has,have,had,will,would,should,could,about,into,over,after,before,between,under,what,when,where,which,while,also,just,then,than,them,they,their,to,of,in,on,at,is,it,as,be,by,we,us,do,if,so,no,my,me,our,your,his,her,its,not,but,all,any,can,how,why,who".split(","));
+/** Max matches returned and max excerpt chars per match (output-token caps). */
+const DEFAULT_MATCH_LIMIT = 8;
+const EXCERPT_CHARS = 1200;
+function tokenize(query) {
+    return [
+        ...new Set(query
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter((t) => t.length >= 2 && !STOPWORDS.has(t))),
+    ];
+}
+function checkName(name) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name)) {
+        throw new MemoryError("INVALID_NAME", `Invalid memory 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;
+    }
+}
+function scoreDoc(fileName, content, tokens) {
+    const lowerName = fileName.toLowerCase();
+    const lowerBody = content.toLowerCase();
+    let score = 0;
+    for (const token of tokens) {
+        if (lowerName.includes(token))
+            score += 2;
+        // Count occurrences, capped so one long file can't dominate.
+        let count = 0;
+        let from = 0;
+        for (;;) {
+            const hit = lowerBody.indexOf(token, from);
+            if (hit === -1 || count >= 5)
+                break;
+            count++;
+            from = hit + token.length;
+        }
+        score += count;
+    }
+    return score;
+}
+function matchesQuery(event, tokens) {
+    const haystack = `${event.kind} ${event.taskId ?? ""} ${event.summary} ${event.details ?? ""}`.toLowerCase();
+    return tokens.some((t) => haystack.includes(t));
+}
+/**
+ * Recall relevant memory. Validates identity first (wrong project or
+ * unavailable vault throws before any read), then reads index + state,
+ * the requested task's docs, query-matching scope docs, and recent logs.
+ * Read-only: never writes, never leaves the validated project scope.
+ */
+export function recallMemory(input) {
+    const identity = validateIdentity(input.projectRoot, input.config);
+    const { vaultRoot, projectId, branch } = identity;
+    const tokens = tokenize(input.query ?? "");
+    const index = readOrNull(resolveVaultDoc(vaultRoot, projectId, "index.md"));
+    const currentState = readOrNull(resolveVaultDoc(vaultRoot, projectId, "current-state.md"));
+    let taskDocs = null;
+    if (input.taskId !== undefined) {
+        taskDocs = {
+            taskId: input.taskId,
+            intent: readOrNull(resolveVaultDoc(vaultRoot, projectId, "tasks", input.taskId, "intent.md")),
+            plan: readOrNull(resolveVaultDoc(vaultRoot, projectId, "tasks", input.taskId, "plan.md")),
+        };
+    }
+    const matches = [];
+    if (tokens.length > 0) {
+        for (const dir of SEARCH_DIRS) {
+            const absDir = resolveVaultDoc(vaultRoot, projectId, dir);
+            for (const file of listMdFiles(absDir)) {
+                const content = readOrNull(resolveVaultDoc(vaultRoot, projectId, dir, file)) ?? "";
+                const score = scoreDoc(file, content, tokens);
+                if (score <= 0)
+                    continue;
+                const truncated = content.length > EXCERPT_CHARS;
+                matches.push({
+                    dir,
+                    file,
+                    score,
+                    excerpt: truncated
+                        ? content.slice(0, EXCERPT_CHARS) + "\n…(truncated)"
+                        : content,
+                    truncated,
+                });
+            }
+        }
+        matches.sort((a, b) => b.score - a.score || (a.file < b.file ? -1 : 1));
+    }
+    let logEvents = [];
+    if (input.includeLogs ?? true) {
+        const events = readLastEvents(vaultRoot, projectId, input.logLimit ?? 10);
+        logEvents = tokens.length > 0 ? events.filter((e) => matchesQuery(e, tokens)) : events;
+    }
+    return {
+        projectId,
+        branch,
+        index,
+        currentState,
+        taskDocs,
+        matches: matches.slice(0, input.limit ?? DEFAULT_MATCH_LIMIT),
+        logEvents,
+    };
+}
+/**
+ * Record one memory note inside the validated project scope.
+ * Identity failures throw before any write; existing notes are never
+ * silently replaced (`overwrite: true` required).
+ * Returns the vault-relative path of the note.
+ */
+export function recordMemory(input) {
+    checkName(input.name);
+    if (typeof input.content !== "string" || input.content.trim() === "") {
+        throw new MemoryError("INVALID_INPUT", "Memory content must be a non-empty string.");
+    }
+    const identity = validateIdentity(input.projectRoot, input.config);
+    writeVaultDoc(resolveVaultDoc(identity.vaultRoot, identity.projectId, "memory", `${input.name}.md`), input.content.endsWith("\n") ? input.content : input.content + "\n", { overwrite: input.overwrite ?? false });
+    return `memory/${input.name}.md`;
+}

package/dist/planning/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * intent.md / plan.md workflow (OLC-032).
+ *
+ * - `draftTaskDocs`: render both templates (status `draft`) and create them
+ *   under `tasks/<taskId>/`. Refuses when docs already exist.
+ * - `approveTaskDocs`: flip both statuses to `approved` (explicit overwrite).
+ * - `reviseTaskDocs`: append the reason to `history.md`, write updated docs,
+ *   reset status to `draft` (re-approval required).
+ * - `rejectTaskDocs`: mark both `rejected` and record the reason in history.
+ * - `assertApproved`: gate for build-side use — throws unless BOTH docs exist
+ *   and are `approved`, naming the offending document.
+ */
+export type PlanningStatus = "draft" | "approved" | "rejected";
+export declare class PlanningError extends Error {
+    readonly code: "NOT_APPROVED" | "MISSING_DOC" | "INVALID_STATUS";
+    constructor(code: "NOT_APPROVED" | "MISSING_DOC" | "INVALID_STATUS", message: string);
+}
+export interface IntentVars {
+    what: string;
+    why: string;
+    nonGoals: string;
+    openQuestions: string;
+}
+export interface PlanVars {
+    approach: string;
+    steps: string;
+    acceptanceCriteria: string;
+    tests: string;
+    risks: string;
+}
+/** Create both docs with status `draft`. Throws (no overwrite) if either exists. */
+export declare function draftTaskDocs(vaultRoot: string, projectId: string, taskId: string, intent: IntentVars, plan: PlanVars): {
+    intentPath: string;
+    planPath: string;
+};
+/** Current statuses of both docs (`missing` when the file does not exist). */
+export declare function getDocStatuses(vaultRoot: string, projectId: string, taskId: string): {
+    intent: PlanningStatus | "missing";
+    plan: PlanningStatus | "missing";
+};
+/** Approve both docs. Both must currently exist (draft or rejected). */
+export declare function approveTaskDocs(vaultRoot: string, projectId: string, taskId: string, date: string): void;
+/**
+ * Revise: record the reason in history, optionally replace doc bodies,
+ * reset both statuses to `draft` so re-approval is required.
+ */
+export declare function reviseTaskDocs(vaultRoot: string, projectId: string, taskId: string, reason: string, date: string, updated?: {
+    intent?: IntentVars;
+    plan?: PlanVars;
+}): void;
+/** Reject both docs and record the reason. A rejected plan blocks builds. */
+export declare function rejectTaskDocs(vaultRoot: string, projectId: string, taskId: string, reason: string, date: string): void;
+/**
+ * Build gate: throws `PlanningError(NOT_APPROVED)` unless both docs exist
+ * and carry status `approved`. Call before any implementation work.
+ */
+export declare function assertApproved(vaultRoot: string, projectId: string, taskId: string): void;

package/dist/planning/index.js

@@ -0,0 +1,180 @@
+/**
+ * intent.md / plan.md workflow (OLC-032).
+ *
+ * - `draftTaskDocs`: render both templates (status `draft`) and create them
+ *   under `tasks/<taskId>/`. Refuses when docs already exist.
+ * - `approveTaskDocs`: flip both statuses to `approved` (explicit overwrite).
+ * - `reviseTaskDocs`: append the reason to `history.md`, write updated docs,
+ *   reset status to `draft` (re-approval required).
+ * - `rejectTaskDocs`: mark both `rejected` and record the reason in history.
+ * - `assertApproved`: gate for build-side use — throws unless BOTH docs exist
+ *   and are `approved`, naming the offending document.
+ */
+import { VaultError, parseFrontmatter, readVaultDoc, renderTemplate, resolveVaultDoc, withFrontmatter, writeVaultDoc, } from "../vault/index.js";
+export class PlanningError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PlanningError";
+        this.code = code;
+    }
+}
+function docPaths(vaultRoot, projectId, taskId) {
+    return {
+        intent: resolveVaultDoc(vaultRoot, projectId, "tasks", taskId, "intent.md"),
+        plan: resolveVaultDoc(vaultRoot, projectId, "tasks", taskId, "plan.md"),
+        history: resolveVaultDoc(vaultRoot, projectId, "tasks", taskId, "history.md"),
+    };
+}
+function templateVars(projectId, taskId, status, extra) {
+    return { project_id: projectId, task_id: taskId, status, ...extra };
+}
+/** Create both docs with status `draft`. Throws (no overwrite) if either exists. */
+export function draftTaskDocs(vaultRoot, projectId, taskId, intent, plan) {
+    const paths = docPaths(vaultRoot, projectId, taskId);
+    const intentText = renderTemplate("intent", templateVars(projectId, taskId, "draft", {
+        what: intent.what,
+        why: intent.why,
+        non_goals: intent.nonGoals,
+        open_questions: intent.openQuestions,
+    }));
+    const planText = renderTemplate("plan", templateVars(projectId, taskId, "draft", {
+        approach: plan.approach,
+        steps: plan.steps,
+        acceptance_criteria: plan.acceptanceCriteria,
+        tests: plan.tests,
+        risks: plan.risks,
+    }));
+    // Write plan first so a failure leaves either both-missing or plan-only;
+    // either way no partial intent exists without its plan. Both use
+    // create-only semantics (existing docs are never silently replaced).
+    writeVaultDoc(paths.plan, planText);
+    try {
+        writeVaultDoc(paths.intent, intentText);
+    }
+    catch (error) {
+        if (error instanceof VaultError && error.code === "ALREADY_EXISTS") {
+            throw new PlanningError("NOT_APPROVED", `Cannot draft task ${taskId}: intent.md already exists and plan.md was just created. ` +
+                "Remove the stray plan.md or revise the existing docs instead — nothing was overwritten.");
+        }
+        throw error;
+    }
+    return { intentPath: paths.intent, planPath: paths.plan };
+}
+function readStatus(path, label) {
+    let text;
+    try {
+        text = readVaultDoc(path);
+    }
+    catch {
+        throw new PlanningError("MISSING_DOC", `Planning document missing: ${label} at ${path}. Draft it before approving.`);
+    }
+    const status = parseFrontmatter(text).data["status"];
+    if (status !== "draft" && status !== "approved" && status !== "rejected") {
+        throw new PlanningError("INVALID_STATUS", `Planning document ${label} has unknown status ${JSON.stringify(status)}. Expected draft, approved, or rejected.`);
+    }
+    return status;
+}
+/** Current statuses of both docs (`missing` when the file does not exist). */
+export function getDocStatuses(vaultRoot, projectId, taskId) {
+    const paths = docPaths(vaultRoot, projectId, taskId);
+    const read = (path, label) => {
+        try {
+            return readStatus(path, label);
+        }
+        catch (error) {
+            if (error instanceof PlanningError && error.code === "MISSING_DOC")
+                return "missing";
+            throw error;
+        }
+    };
+    return { intent: read(paths.intent, "intent.md"), plan: read(paths.plan, "plan.md") };
+}
+function setStatus(vaultRoot, projectId, taskId, status) {
+    const paths = docPaths(vaultRoot, projectId, taskId);
+    for (const [path, label] of [
+        [paths.intent, "intent.md"],
+        [paths.plan, "plan.md"],
+    ]) {
+        const parsed = parseFrontmatter(readVaultDoc(path));
+        writeVaultDoc(path, withFrontmatter({ ...parsed.data, status }, parsed.body), {
+            overwrite: true,
+        });
+    }
+}
+function appendHistory(vaultRoot, projectId, taskId, kind, reason, date) {
+    const { history } = docPaths(vaultRoot, projectId, taskId);
+    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,
+    });
+}
+/** Approve both docs. Both must currently exist (draft or rejected). */
+export function approveTaskDocs(vaultRoot, projectId, taskId, date) {
+    const paths = docPaths(vaultRoot, projectId, taskId);
+    readStatus(paths.intent, "intent.md");
+    readStatus(paths.plan, "plan.md");
+    setStatus(vaultRoot, projectId, taskId, "approved");
+    appendHistory(vaultRoot, projectId, taskId, "approved", "Approved by user.", date);
+}
+/**
+ * Revise: record the reason in history, optionally replace doc bodies,
+ * reset both statuses to `draft` so re-approval is required.
+ */
+export function reviseTaskDocs(vaultRoot, projectId, taskId, reason, date, updated) {
+    appendHistory(vaultRoot, projectId, taskId, "revision", reason, date);
+    if (updated?.intent) {
+        const paths = docPaths(vaultRoot, projectId, taskId);
+        writeVaultDoc(paths.intent, renderTemplate("intent", templateVars(projectId, taskId, "draft", {
+            what: updated.intent.what,
+            why: updated.intent.why,
+            non_goals: updated.intent.nonGoals,
+            open_questions: updated.intent.openQuestions,
+        })), { overwrite: true });
+    }
+    if (updated?.plan) {
+        const paths = docPaths(vaultRoot, projectId, taskId);
+        writeVaultDoc(paths.plan, renderTemplate("plan", templateVars(projectId, taskId, "draft", {
+            approach: updated.plan.approach,
+            steps: updated.plan.steps,
+            acceptance_criteria: updated.plan.acceptanceCriteria,
+            tests: updated.plan.tests,
+            risks: updated.plan.risks,
+        })), { overwrite: true });
+    }
+    setStatus(vaultRoot, projectId, taskId, "draft");
+}
+/** Reject both docs and record the reason. A rejected plan blocks builds. */
+export function rejectTaskDocs(vaultRoot, projectId, taskId, reason, date) {
+    const paths = docPaths(vaultRoot, projectId, taskId);
+    readStatus(paths.intent, "intent.md");
+    readStatus(paths.plan, "plan.md");
+    setStatus(vaultRoot, projectId, taskId, "rejected");
+    appendHistory(vaultRoot, projectId, taskId, "rejected", reason, date);
+}
+/**
+ * Build gate: throws `PlanningError(NOT_APPROVED)` unless both docs exist
+ * and carry status `approved`. Call before any implementation work.
+ */
+export function assertApproved(vaultRoot, projectId, taskId) {
+    const statuses = getDocStatuses(vaultRoot, projectId, taskId);
+    const problems = [];
+    for (const [label, status] of [
+        ["intent.md", statuses.intent],
+        ["plan.md", statuses.plan],
+    ]) {
+        if (status !== "approved")
+            problems.push(`${label} is ${status}`);
+    }
+    if (problems.length > 0) {
+        throw new PlanningError("NOT_APPROVED", `Task ${taskId} is not approved for implementation: ${problems.join("; ")}. ` +
+            "Draft, revise, and get both documents approved before coding.");
+    }
+}

package/dist/plugin.d.ts

@@ -0,0 +1,16 @@
+/**
+ * OLC OpenCode plugin entrypoint (OLC-011).
+ *
+ * Deliberately minimal: registers one read-only diagnostic tool
+ * (`olc_status`) that reports the OLC package version and the detected
+ * project location. No file writes happen at import or setup time —
+ * acceptance criteria for OLC-011 requires no surprise writes on load.
+ *
+ * Uses `@opencode/plugin` (v2 promise API, matching the running
+ * `opencode` CLI): `Plugin.define({ id, setup })` with
+ * `ctx.tool.transform` for tool registration and `ctx.location`
+ * for project context.
+ */
+import { Plugin } from "@opencode/plugin";
+declare const _default: Plugin.Plugin;
+export default _default;

package/dist/plugin.js

@@ -0,0 +1,46 @@
+/**
+ * OLC OpenCode plugin entrypoint (OLC-011).
+ *
+ * Deliberately minimal: registers one read-only diagnostic tool
+ * (`olc_status`) that reports the OLC package version and the detected
+ * project location. No file writes happen at import or setup time —
+ * acceptance criteria for OLC-011 requires no surprise writes on load.
+ *
+ * Uses `@opencode/plugin` (v2 promise API, matching the running
+ * `opencode` CLI): `Plugin.define({ id, setup })` with
+ * `ctx.tool.transform` for tool registration and `ctx.location`
+ * for project context.
+ */
+import { Plugin } from "@opencode/plugin";
+import { OLC_VERSION } from "./index.js";
+export default Plugin.define({
+    id: "olc",
+    async setup(ctx) {
+        await ctx.tool.transform((editor) => {
+            editor.namespace({
+                name: "olc",
+                description: "Obsidian Lean Coder diagnostics",
+            });
+            editor.add({
+                name: "status",
+                description: "Report the OLC package version and the detected project location. Read-only, makes no writes.",
+                input: {
+                    type: "object",
+                    properties: {},
+                    additionalProperties: false,
+                },
+                options: { namespace: "olc" },
+                execute: async () => {
+                    return {
+                        content: JSON.stringify({
+                            olcVersion: OLC_VERSION,
+                            directory: ctx.location.directory,
+                            projectId: ctx.location.project.id,
+                            canonical: ctx.location.project.canonical,
+                        }, null, 2),
+                    };
+                },
+            });
+        });
+    },
+});

package/dist/resume/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Resume context (OLC-061): rebuild enough context after an interruption.
+ *
+ * Read-only. Never resumes coding, switches branches, or closes tasks —
+ * every result carries `needsConfirmation: true`, and ambiguous situations
+ * set `blocked` with an actionable message instead of guessing.
+ *
+ * Contents: actual Git state (branch/HEAD/staged/unstaged/untracked),
+ * `current-state.md`, open registry tasks (newest first), the recommended
+ * task (via OLC-033 `recommendResume`), that task's intent/plan doc
+ * statuses, the most recent log events (last verification visible there),
+ * and the most recent checkpoint event. Identity is validated first, so an
+ * unavailable vault or mismatched project fails before anything is read.
+ * A detached HEAD does not nuke the context: branch is reported as null
+ * (vault-side checks still apply) and the result is marked blocked.
+ */
+import type { ResolvedConfig } from "../config/index.js";
+import { type LoggedEvent } from "../log/index.js";
+import { type TaskEntry } from "../tasks/index.js";
+export interface ResumeTask {
+    taskId: string;
+    entry: TaskEntry;
+}
+export interface ResumeCheckpoint {
+    taskId?: string;
+    gitSha: string;
+    date: string;
+    summary: string;
+}
+export interface ResumeContext {
+    branch: string | null;
+    head: string;
+    staged: string[];
+    unstaged: string[];
+    untracked: string[];
+    currentState: string | null;
+    /** Non-terminal registry tasks, newest `updatedAt` first. */
+    openTasks: ResumeTask[];
+    recommendedTaskId: string | null;
+    recommendationNote: string;
+    /** Intent/plan doc statuses for the recommended task, null when none. */
+    taskDocs: {
+        intent: string;
+        plan: string;
+    } | null;
+    /** Newest-first log events (surfaces the last verification). */
+    lastEvents: LoggedEvent[];
+    lastCheckpoint: ResumeCheckpoint | null;
+    /** Always true: resuming requires explicit user confirmation. */
+    needsConfirmation: true;
+    /** Non-null when ambiguity blocks even a recommendation. */
+    blocked: string | null;
+}
+export interface ResumeArgs {
+    projectRoot: string;
+    config: ResolvedConfig;
+    /** How many recent log events to include. Default 5. */
+    lastEventsLimit?: number;
+}
+export declare function buildResumeContext(args: ResumeArgs): ResumeContext;

package/dist/resume/index.js

@@ -0,0 +1,121 @@
+/**
+ * Resume context (OLC-061): rebuild enough context after an interruption.
+ *
+ * Read-only. Never resumes coding, switches branches, or closes tasks —
+ * every result carries `needsConfirmation: true`, and ambiguous situations
+ * set `blocked` with an actionable message instead of guessing.
+ *
+ * Contents: actual Git state (branch/HEAD/staged/unstaged/untracked),
+ * `current-state.md`, open registry tasks (newest first), the recommended
+ * task (via OLC-033 `recommendResume`), that task's intent/plan doc
+ * statuses, the most recent log events (last verification visible there),
+ * and the most recent checkpoint event. Identity is validated first, so an
+ * unavailable vault or mismatched project fails before anything is read.
+ * A detached HEAD does not nuke the context: branch is reported as null
+ * (vault-side checks still apply) and the result is marked blocked.
+ */
+import { resolve } from "node:path";
+import { IdentityError, assertVaultAccessible, readRegistry as readVaultRegistry, resolveRepoRoot, validateIdentity, } from "../core/project-identity.js";
+import { git, parsePorcelain } from "../git/inspection.js";
+import { readLastEvents } from "../log/index.js";
+import { getDocStatuses } from "../planning/index.js";
+import { TERMINAL_STATUSES, readRegistry, recommendResume, } from "../tasks/index.js";
+import { readVaultDoc, resolveVaultDoc } from "../vault/index.js";
+function readCurrentState(vaultRoot, projectId) {
+    try {
+        return readVaultDoc(resolveVaultDoc(vaultRoot, projectId, "current-state.md"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export function buildResumeContext(args) {
+    const limit = args.lastEventsLimit ?? 5;
+    let branch;
+    let repoRoot;
+    let vaultRoot;
+    let projectId;
+    try {
+        const identity = validateIdentity(args.projectRoot, args.config);
+        repoRoot = identity.repoRoot;
+        branch = identity.branch;
+        vaultRoot = identity.vaultRoot;
+        projectId = identity.projectId;
+    }
+    catch (error) {
+        if (error instanceof IdentityError && error.code === "DETACHED_HEAD") {
+            // Unknown branch must not hide everything else: the vault-side
+            // checks still apply, branch is reported as null, and the result
+            // is marked blocked below.
+            repoRoot = resolveRepoRoot(args.projectRoot);
+            vaultRoot = args.config.vaultPath;
+            projectId = args.config.projectId;
+            assertVaultAccessible(vaultRoot);
+            const entry = readVaultRegistry(vaultRoot).projects[projectId];
+            if (!entry || resolve(entry.repoRoot) !== repoRoot) {
+                throw new IdentityError("PROJECT_MISMATCH", `project_id "${projectId}" is not registered to repository ${repoRoot} in vault ${vaultRoot}. ` +
+                    "Refusing to touch the wrong project's memory.");
+            }
+            branch = null;
+        }
+        else {
+            throw error;
+        }
+    }
+    const head = git(repoRoot, ["rev-parse", "HEAD"]);
+    const sets = parsePorcelain(git(repoRoot, ["status", "--porcelain=v1", "-uall"]));
+    const registry = readRegistry(vaultRoot, projectId);
+    const openTasks = Object.entries(registry.tasks)
+        .filter(([, e]) => !TERMINAL_STATUSES.includes(e.status))
+        .sort((a, b) => (a[1].updatedAt < b[1].updatedAt ? 1 : -1))
+        .map(([taskId, entry]) => ({ taskId, entry }));
+    const recommendation = recommendResume(vaultRoot, projectId, branch);
+    const lastEvents = readLastEvents(vaultRoot, projectId, limit);
+    const checkpointEvent = lastEvents.find((e) => e.kind === "checkpoint" && e.gitSha);
+    const lastCheckpoint = checkpointEvent?.gitSha
+        ? {
+            taskId: checkpointEvent.taskId,
+            gitSha: checkpointEvent.gitSha,
+            date: checkpointEvent.date,
+            summary: checkpointEvent.summary,
+        }
+        : null;
+    let blocked = null;
+    if (branch === null) {
+        blocked =
+            "Current branch is unknown (detached HEAD). Tell me which branch and task to resume, and confirm — nothing was switched or closed.";
+    }
+    else if (recommendation.taskId === null && openTasks.length > 0) {
+        blocked =
+            `${openTasks.length} open task(s) exist but none is attached to branch ${branch}. ` +
+                "Tell me which task to resume, and confirm — nothing was switched or closed.";
+    }
+    else {
+        const onBranch = openTasks.filter((t) => t.entry.branch === branch);
+        if (onBranch.length > 1 && onBranch[0].entry.updatedAt === onBranch[1].entry.updatedAt) {
+            blocked =
+                `Tasks ${onBranch[0].taskId} and ${onBranch[1].taskId} are equally recent on branch ${branch}. ` +
+                    "Tell me which one to resume, and confirm — nothing was switched or closed.";
+        }
+    }
+    return {
+        branch,
+        head,
+        staged: sets.staged,
+        unstaged: sets.unstaged,
+        untracked: sets.untracked,
+        currentState: readCurrentState(vaultRoot, projectId),
+        openTasks,
+        recommendedTaskId: recommendation.taskId,
+        recommendationNote: recommendation.note,
+        taskDocs: recommendation.taskId === null
+            ? null
+            : getDocStatuses(vaultRoot, projectId, recommendation.taskId),
+        lastEvents,
+        lastCheckpoint,
+        needsConfirmation: true,
+        blocked,
+    };
+}