grounder 0.1.0 → 0.3.0

package/dist/util/path.js.map

@@ -1 +1 @@
-{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/util/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE;IACxE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/util/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE;IACxE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,KAAa;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,OAAO,CACL,QAAQ,KAAK,EAAE;QACf,QAAQ,KAAK,IAAI;QACjB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;QACrC,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAc,EAAE,KAAa;IAClE,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;QACrC,OAAO,IAAI,KAAK,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/util/plan-name.d.ts

@@ -0,0 +1,10 @@
+/** Generous cap for plan filenames — real plan names often exceed note/handoff's 20-char slug. */
+export declare const MAX_PLAN_NAME_LENGTH = 80;
+/**
+ * Sanitize a `--title` value into a filename-safe plan name.
+ * Trims, strips a trailing `.md` (case-insensitive), applies {@link sanitizeProjectId}
+ * character rules, and caps at {@link MAX_PLAN_NAME_LENGTH}.
+ * Returns `""` when the result is empty / unusable.
+ */
+export declare function sanitizePlanName(rawTitle: string): string;
+//# sourceMappingURL=plan-name.d.ts.map

package/dist/util/plan-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-name.d.ts","sourceRoot":"","sources":["../../src/util/plan-name.ts"],"names":[],"mappings":"AAEA,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOzD"}

package/dist/util/plan-name.js

@@ -0,0 +1,18 @@
+import { sanitizeProjectId } from "./project-id.js";
+/** Generous cap for plan filenames — real plan names often exceed note/handoff's 20-char slug. */
+export const MAX_PLAN_NAME_LENGTH = 80;
+/**
+ * Sanitize a `--title` value into a filename-safe plan name.
+ * Trims, strips a trailing `.md` (case-insensitive), applies {@link sanitizeProjectId}
+ * character rules, and caps at {@link MAX_PLAN_NAME_LENGTH}.
+ * Returns `""` when the result is empty / unusable.
+ */
+export function sanitizePlanName(rawTitle) {
+    const trimmed = rawTitle.trim().replace(/\.md$/i, "");
+    const sanitized = sanitizeProjectId(trimmed);
+    if (!sanitized) {
+        return "";
+    }
+    return sanitized.slice(0, MAX_PLAN_NAME_LENGTH).replace(/-+$/g, "");
+}
+//# sourceMappingURL=plan-name.js.map

package/dist/util/plan-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-name.js","sourceRoot":"","sources":["../../src/util/plan-name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,kGAAkG;AAClG,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/util/semver.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Compare npm-style `major.minor.patch` prefixes.
+ * Returns negative / zero / positive like `strcmp`, or `null` if either side
+ * lacks a leading `x.y.z` (prerelease/build suffixes after the triple are ignored).
+ */
+export declare function compareSemver(a: string, b: string): number | null;
+/** How the running package version relates to the last-recorded ledger version. */
+export type PackageVersionRelation = "match" | "ahead" | "behind" | "differs";
+export declare function packageVersionRelation(running: string, recorded: string): PackageVersionRelation;
+//# sourceMappingURL=semver.d.ts.map

package/dist/util/semver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver.d.ts","sourceRoot":"","sources":["../../src/util/semver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwBjE;AAED,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAUhG"}

package/dist/util/semver.js

@@ -0,0 +1,40 @@
+/**
+ * Compare npm-style `major.minor.patch` prefixes.
+ * Returns negative / zero / positive like `strcmp`, or `null` if either side
+ * lacks a leading `x.y.z` (prerelease/build suffixes after the triple are ignored).
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => {
+        const match = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+        if (!match) {
+            return null;
+        }
+        return [Number(match[1]), Number(match[2]), Number(match[3])];
+    };
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right) {
+        return null;
+    }
+    for (let i = 0; i < 3; i++) {
+        if (left[i] < right[i]) {
+            return -1;
+        }
+        if (left[i] > right[i]) {
+            return 1;
+        }
+    }
+    return 0;
+}
+export function packageVersionRelation(running, recorded) {
+    if (running === recorded) {
+        return "match";
+    }
+    const cmp = compareSemver(running, recorded);
+    if (cmp === null || cmp === 0) {
+        // Unparseable, or same x.y.z with different suffix/string form.
+        return "differs";
+    }
+    return cmp > 0 ? "ahead" : "behind";
+}
+//# sourceMappingURL=semver.js.map

package/dist/util/semver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver.js","sourceRoot":"","sources":["../../src/util/semver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,CAAS;IAChD,MAAM,KAAK,GAAG,CAAC,CAAS,EAAmC,EAAE;QAC3D,MAAM,KAAK,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,CAAC,CAAC;QACZ,CAAC;QACD,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAKD,MAAM,UAAU,sBAAsB,CAAC,OAAe,EAAE,QAAgB;IACtE,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC7C,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;QAC9B,gEAAgE;QAChE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;AACtC,CAAC"}

package/dist/vault/find-usable-handoff.d.ts

@@ -0,0 +1,19 @@
+export interface FindUsableHandoffOptions {
+    /** Max newest-first candidates to scan (default: 5). */
+    limit?: number;
+}
+export interface UsableHandoff {
+    /** Absolute path of the resolved handoff file. */
+    path: string;
+    /** Already-read file contents (avoids a second read by callers). */
+    content: string;
+}
+/**
+ * Resolves the newest-first handoff under `logsDir` that actually has content,
+ * skipping empty or unreadable files along the way (e.g. an interrupted write).
+ * Single source of truth for "which handoff is current" — shared by
+ * `grounder handoff peek` and `grounder handoff list --head` so both agree.
+ * Returns `undefined` when no candidate within the scan window is usable.
+ */
+export declare function findUsableHandoff(logsDir: string, options?: FindUsableHandoffOptions): Promise<UsableHandoff | undefined>;
+//# sourceMappingURL=find-usable-handoff.d.ts.map

package/dist/vault/find-usable-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-usable-handoff.d.ts","sourceRoot":"","sources":["../../src/vault/find-usable-handoff.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,wBAAwB;IACvC,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAcpC"}

package/dist/vault/find-usable-handoff.js

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import { listHandoffs } from "./list-handoffs.js";
+/** Newest-first candidates scanned for a usable handoff before giving up. */
+const DEFAULT_SCAN_LIMIT = 5;
+/**
+ * Resolves the newest-first handoff under `logsDir` that actually has content,
+ * skipping empty or unreadable files along the way (e.g. an interrupted write).
+ * Single source of truth for "which handoff is current" — shared by
+ * `grounder handoff peek` and `grounder handoff list --head` so both agree.
+ * Returns `undefined` when no candidate within the scan window is usable.
+ */
+export async function findUsableHandoff(logsDir, options = {}) {
+    const paths = await listHandoffs(logsDir, { limit: options.limit ?? DEFAULT_SCAN_LIMIT });
+    for (const filePath of paths) {
+        let content;
+        try {
+            content = await readFile(filePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (content.trim().length > 0) {
+            return { path: filePath, content };
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=find-usable-handoff.js.map

package/dist/vault/find-usable-handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-usable-handoff.js","sourceRoot":"","sources":["../../src/vault/find-usable-handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,6EAA6E;AAC7E,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAc7B;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAe,EACf,UAAoC,EAAE;IAEtC,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,kBAAkB,EAAE,CAAC,CAAC;IAC1F,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC7B,IAAI,OAAe,CAAC;QACpB,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;QACrC,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/vault/layout.d.ts

@@ -10,4 +10,6 @@ export declare function projectDir(vaultRoot: string, projectId: string): string
 export declare function notesDir(vaultRoot: string, projectId: string): string;
 /** `<vault>/10-Projects/{projectId}/logs` — session handoffs. */
 export declare function logsDir(vaultRoot: string, projectId: string): string;
+/** `<vault>/10-Projects/{projectId}/plans` — named, updatable plan docs. */
+export declare function plansDir(vaultRoot: string, projectId: string): string;
 //# sourceMappingURL=layout.d.ts.map

package/dist/vault/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/vault/layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAE1C,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,yCAAyC;AACzC,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,iEAAiE;AACjE,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpE"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/vault/layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAE1C,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,yCAAyC;AACzC,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,iEAAiE;AACjE,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAErE"}

package/dist/vault/layout.js

@@ -19,4 +19,8 @@ export function notesDir(vaultRoot, projectId) {
 export function logsDir(vaultRoot, projectId) {
     return path.join(vaultRoot, PROJECTS_DIR, projectId, "logs");
 }
+/** `<vault>/10-Projects/{projectId}/plans` — named, updatable plan docs. */
+export function plansDir(vaultRoot, projectId) {
+    return path.join(vaultRoot, PROJECTS_DIR, projectId, "plans");
+}
 //# sourceMappingURL=layout.js.map

package/dist/vault/layout.js.map

@@ -1 +1 @@
-{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../src/vault/layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;AAE1C,6DAA6D;AAC7D,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAC5C,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,SAAiB;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,QAAQ,CAAC,SAAiB,EAAE,SAAiB;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,OAAO,CAAC,SAAiB,EAAE,SAAiB;IAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../src/vault/layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;AAE1C,6DAA6D;AAC7D,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAC5C,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,SAAiB;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,QAAQ,CAAC,SAAiB,EAAE,SAAiB;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,OAAO,CAAC,SAAiB,EAAE,SAAiB;IAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AAC/D,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAC,SAAiB,EAAE,SAAiB;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC"}

package/dist/vault/list-plans.d.ts

@@ -0,0 +1,11 @@
+export interface ListPlansOptions {
+    /** Max paths to return (newest first). Omit to return all. */
+    limit?: number;
+}
+/**
+ * Lists plan markdown files under `plansDir`, newest mtime first.
+ * Returns absolute paths. Missing or empty dirs yield `[]`.
+ * Ties break by filename descending for stable output.
+ */
+export declare function listPlans(plansDir: string, options?: ListPlansOptions): Promise<string[]>;
+//# sourceMappingURL=list-plans.d.ts.map

package/dist/vault/list-plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-plans.d.ts","sourceRoot":"","sources":["../../src/vault/list-plans.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAoCnB"}

package/dist/vault/list-plans.js

@@ -0,0 +1,40 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Lists plan markdown files under `plansDir`, newest mtime first.
+ * Returns absolute paths. Missing or empty dirs yield `[]`.
+ * Ties break by filename descending for stable output.
+ */
+export async function listPlans(plansDir, options = {}) {
+    let entries;
+    try {
+        entries = await readdir(plansDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const mdNames = entries.filter((name) => name.endsWith(".md"));
+    const withMtime = await Promise.all(mdNames.map(async (name) => {
+        const filePath = path.join(plansDir, name);
+        const { mtimeMs } = await stat(filePath);
+        return { filePath, name, mtimeMs };
+    }));
+    withMtime.sort((a, b) => {
+        if (a.mtimeMs !== b.mtimeMs) {
+            return b.mtimeMs - a.mtimeMs;
+        }
+        return a.name < b.name ? 1 : a.name > b.name ? -1 : 0;
+    });
+    const paths = withMtime.map((entry) => entry.filePath);
+    if (options.limit === undefined) {
+        return paths;
+    }
+    if (options.limit <= 0) {
+        return [];
+    }
+    return paths.slice(0, options.limit);
+}
+//# sourceMappingURL=list-plans.js.map

package/dist/vault/list-plans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-plans.js","sourceRoot":"","sources":["../../src/vault/list-plans.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,IAAI,MAAM,WAAW,CAAC;AAO7B;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,UAA4B,EAAE;IAE9B,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,GAAG,CACjC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC3C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACrC,CAAC,CAAC,CACH,CAAC;IAEF,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACtB,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YAC5B,OAAO,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QAC/B,CAAC;QACD,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAEvD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}

package/dist/vault/write-plan.d.ts

@@ -0,0 +1,28 @@
+/** Options for {@link writePlan}. */
+export interface WritePlanOptions {
+    /** Project id written into YAML frontmatter. */
+    projectId: string;
+    /** When true, overwrite an existing plan (preserving original `created`). */
+    force?: boolean;
+    /** Timestamp for `created` / `updated` (default: now). */
+    now?: Date;
+}
+export type WritePlanStatus = "created" | "overwritten" | "exists";
+export interface WritePlanResult {
+    path: string;
+    status: WritePlanStatus;
+}
+/**
+ * Overwrites an existing plan at an absolute path.
+ * Preserves original `created` (falls back to `now` if missing) and sets `updated`.
+ * Caller must validate the path (e.g. inside this project's `plans/` dir).
+ */
+export declare function updatePlanAtPath(filePath: string, body: string, options: Omit<WritePlanOptions, "force">): Promise<WritePlanResult>;
+/**
+ * Writes or updates a named plan markdown file under `plansDir` (created if missing).
+ * Target is always `plansDir/<name>.md` — no collision suffixes.
+ * Without `force`, an existing file is left untouched and status `"exists"` is returned.
+ * With `force`, overwrites the body, preserves original `created`, and sets `updated`.
+ */
+export declare function writePlan(plansDir: string, name: string, body: string, options: WritePlanOptions): Promise<WritePlanResult>;
+//# sourceMappingURL=write-plan.d.ts.map

package/dist/vault/write-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-plan.d.ts","sourceRoot":"","sources":["../../src/vault/write-plan.ts"],"names":[],"mappings":"AAMA,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;AAEnE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;CACzB;AAmBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC,CAgB1B;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAuB1B"}

package/dist/vault/write-plan.js

@@ -0,0 +1,61 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseHandoffFrontmatter } from "../util/frontmatter.js";
+import { fileExists } from "../util/fs.js";
+import { yamlDoubleQuoted } from "../util/yaml.js";
+function buildFrontmatter(options) {
+    const lines = [
+        "---",
+        `project: ${yamlDoubleQuoted(options.projectId)}`,
+        `created: ${yamlDoubleQuoted(options.created)}`,
+    ];
+    if (options.updated) {
+        lines.push(`updated: ${yamlDoubleQuoted(options.updated)}`);
+    }
+    lines.push("---");
+    return `${lines.join("\n")}\n\n`;
+}
+/**
+ * Overwrites an existing plan at an absolute path.
+ * Preserves original `created` (falls back to `now` if missing) and sets `updated`.
+ * Caller must validate the path (e.g. inside this project's `plans/` dir).
+ */
+export async function updatePlanAtPath(filePath, body, options) {
+    const now = options.now ?? new Date();
+    const existing = await readFile(filePath, "utf8");
+    const fm = parseHandoffFrontmatter(existing);
+    const created = fm.created ?? now.toISOString();
+    const updated = now.toISOString();
+    const content = buildFrontmatter({
+        projectId: options.projectId,
+        created,
+        updated,
+    }) + body;
+    await writeFile(filePath, content, "utf8");
+    return { path: filePath, status: "overwritten" };
+}
+/**
+ * Writes or updates a named plan markdown file under `plansDir` (created if missing).
+ * Target is always `plansDir/<name>.md` — no collision suffixes.
+ * Without `force`, an existing file is left untouched and status `"exists"` is returned.
+ * With `force`, overwrites the body, preserves original `created`, and sets `updated`.
+ */
+export async function writePlan(plansDir, name, body, options) {
+    const now = options.now ?? new Date();
+    await mkdir(plansDir, { recursive: true });
+    const filePath = path.join(plansDir, `${name}.md`);
+    const exists = await fileExists(filePath);
+    if (exists && !options.force) {
+        return { path: filePath, status: "exists" };
+    }
+    if (exists && options.force) {
+        return updatePlanAtPath(filePath, body, { projectId: options.projectId, now });
+    }
+    const content = buildFrontmatter({
+        projectId: options.projectId,
+        created: now.toISOString(),
+    }) + body;
+    await writeFile(filePath, content, "utf8");
+    return { path: filePath, status: "created" };
+}
+//# sourceMappingURL=write-plan.js.map

package/dist/vault/write-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-plan.js","sourceRoot":"","sources":["../../src/vault/write-plan.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grounder",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Connect git projects to Obsidian dev vaults for AI agent memory",
   "type": "module",
   "bin": {

package/templates/agents/claude/commands/grounder-note.md

@@ -2,7 +2,7 @@ Save a note to the Obsidian vault for this project.
 
 Run from the linked project folder or any subdirectory beneath it:
 
-  npx grounder note "<user text>"
+  {{GROUNDER_CLI}} note "<user text>"
 
 The vault is outside the workspace — grant shell permissions if Claude Code prompts you.
 

package/templates/agents/claude/commands/grounder-plan.md

@@ -0,0 +1,65 @@
+Write a named, updatable plan document to the Obsidian vault for this project.
+
+Distill the instruction after `/grounder-plan` into a structured plan — not a chat transcript.
+Do not dump tool traces, full conversation, or false starts.
+
+Build a markdown body with these sections:
+
+```markdown
+# Plan: <title>
+
+## Goal
+…
+
+## Steps
+1. …
+2. …
+
+## Decisions / open questions
+- …
+
+## Status
+…
+```
+
+Update vs create — never guess a `--title` for an update:
+
+**1. Path known** (attached/open in chat, or printed by an earlier `grounder plan` this conversation): update that exact file.
+
+```bash
+{{GROUNDER_CLI}} plan "$(cat <<'EOF'
+# Plan: …
+…
+EOF
+)" --path <path-to-existing-plan.md>
+```
+
+`--path` must resolve under this project's `plans/` dir; it always overwrites (no `--force`).
+
+**2. Path unknown** (e.g. "update the plan" with nothing attached and no prior path this conversation): look it up, then update as in (1).
+
+```bash
+{{GROUNDER_CLI}} plan list --limit 5
+```
+
+Pick the path matching the user's intent; ask if none or several match.
+
+**3. Genuinely new plan** (not an update): derive a `--title`.
+- If the instruction names one explicitly (e.g. `save as "implementation-phase-1"` or `…phase-1.md`), use it (strip a trailing `.md`).
+- Otherwise derive a short kebab-case name from the plan's title/goal and confirm it with the user before writing.
+
+```bash
+{{GROUNDER_CLI}} plan "$(cat <<'EOF'
+# Plan: …
+…
+EOF
+)" --title <name>
+```
+
+If the CLI refuses because that name already exists (non-zero exit; stderr names the conflict), tell the user and ask whether to overwrite (`--force`) or pick a different name. `--force` only resolves this title collision — it is never how you update a plan you already meant to target (use `--path` for that). **Never** silently pass `--force`.
+
+Run from the linked project folder or any subdirectory beneath it.
+The vault is outside the workspace — grant shell permissions if Claude Code prompts you.
+
+Do not compute vault paths or write files yourself — the CLI handles it.
+Report the CLI output path from stdout to the user.

package/templates/agents/claude/commands/grounder-task-handoff.md

@@ -32,16 +32,16 @@ Rules:
 
 Then run from the linked project folder or any subdirectory beneath it:
 
-  npx grounder handoff "<body>"
+  {{GROUNDER_CLI}} handoff "<body>"
 
 Optional short title slug (filename + frontmatter):
 
-  npx grounder handoff --title <slug> "<body>"
+  {{GROUNDER_CLI}} handoff --title <slug> "<body>"
 
 For multi-line bodies, prefer a shell heredoc so quoting does not break:
 
 ```bash
-npx grounder handoff "$(cat <<'EOF'
+{{GROUNDER_CLI}} handoff "$(cat <<'EOF'
 # Handoff: …
 …
 EOF

package/templates/agents/claude/commands/grounder-task.md

@@ -4,13 +4,13 @@ Read-only — do not write to the vault. Do not invent vault paths.
 
 From the linked project folder or any subdirectory beneath it:
 
-1. List recent handoffs (newest first):
+1. Get the current handoff (skips empty/unreadable files, same pick as the session-start teaser):
 
-   npx grounder handoff list --limit 5
+   {{GROUNDER_CLI}} handoff list --head
 
-2. If the list is empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
+2. If empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
 
-3. If handoffs exist: read the newest file (first path). Optionally skim other listed paths if the user names a session or the newest is clearly wrong.
+3. Otherwise, read that file. If the user names a specific session instead, run `{{GROUNDER_CLI}} handoff list --limit 5` and read the path they mean.
 
 4. Read repo `AGENTS.md` (project conventions and constraints).
 

package/templates/agents/cursor/commands/grounder-note.md

@@ -2,7 +2,7 @@ Save a note to the Obsidian vault for this project.
 
 Run from the linked project folder or any subdirectory beneath it:
 
-  npx grounder note "<user text>"
+  {{GROUNDER_CLI}} note "<user text>"
 
 The vault is outside the workspace — approve shell permissions if Cursor prompts you.
 

package/templates/agents/cursor/commands/grounder-plan.md

@@ -0,0 +1,65 @@
+Write a named, updatable plan document to the Obsidian vault for this project.
+
+Distill the instruction after `/grounder-plan` into a structured plan — not a chat transcript.
+Do not dump tool traces, full conversation, or false starts.
+
+Build a markdown body with these sections:
+
+```markdown
+# Plan: <title>
+
+## Goal
+…
+
+## Steps
+1. …
+2. …
+
+## Decisions / open questions
+- …
+
+## Status
+…
+```
+
+Update vs create — never guess a `--title` for an update:
+
+**1. Path known** (attached/open in chat, or printed by an earlier `grounder plan` this conversation): update that exact file.
+
+```bash
+{{GROUNDER_CLI}} plan "$(cat <<'EOF'
+# Plan: …
+…
+EOF
+)" --path <path-to-existing-plan.md>
+```
+
+`--path` must resolve under this project's `plans/` dir; it always overwrites (no `--force`).
+
+**2. Path unknown** (e.g. "update the plan" with nothing attached and no prior path this conversation): look it up, then update as in (1).
+
+```bash
+{{GROUNDER_CLI}} plan list --limit 5
+```
+
+Pick the path matching the user's intent; ask if none or several match.
+
+**3. Genuinely new plan** (not an update): derive a `--title`.
+- If the instruction names one explicitly (e.g. `save as "implementation-phase-1"` or `…phase-1.md`), use it (strip a trailing `.md`).
+- Otherwise derive a short kebab-case name from the plan's title/goal and confirm it with the user before writing.
+
+```bash
+{{GROUNDER_CLI}} plan "$(cat <<'EOF'
+# Plan: …
+…
+EOF
+)" --title <name>
+```
+
+If the CLI refuses because that name already exists (non-zero exit; stderr names the conflict), tell the user and ask whether to overwrite (`--force`) or pick a different name. `--force` only resolves this title collision — it is never how you update a plan you already meant to target (use `--path` for that). **Never** silently pass `--force`.
+
+Run from the linked project folder or any subdirectory beneath it.
+The vault is outside the workspace — approve shell permissions if Cursor prompts you.
+
+Do not compute vault paths or write files yourself — the CLI handles it.
+Report the CLI output path from stdout to the user.

package/templates/agents/cursor/commands/grounder-task-handoff.md

@@ -32,16 +32,16 @@ Rules:
 
 Then run from the linked project folder or any subdirectory beneath it:
 
-  npx grounder handoff "<body>"
+  {{GROUNDER_CLI}} handoff "<body>"
 
 Optional short title slug (filename + frontmatter):
 
-  npx grounder handoff --title <slug> "<body>"
+  {{GROUNDER_CLI}} handoff --title <slug> "<body>"
 
 For multi-line bodies, prefer a shell heredoc so quoting does not break:
 
 ```bash
-npx grounder handoff "$(cat <<'EOF'
+{{GROUNDER_CLI}} handoff "$(cat <<'EOF'
 # Handoff: …
 …
 EOF

package/templates/agents/cursor/commands/grounder-task.md

@@ -4,13 +4,13 @@ Read-only — do not write to the vault. Do not invent vault paths.
 
 From the linked project folder or any subdirectory beneath it:
 
-1. List recent handoffs (newest first):
+1. Get the current handoff (skips empty/unreadable files, same pick as the session-start teaser):
 
-   npx grounder handoff list --limit 5
+   {{GROUNDER_CLI}} handoff list --head
 
-2. If the list is empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
+2. If empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
 
-3. If handoffs exist: read the newest file (first path). Optionally skim other listed paths if the user names a session or the newest is clearly wrong.
+3. Otherwise, read that file. If the user names a specific session instead, run `{{GROUNDER_CLI}} handoff list --limit 5` and read the path they mean.
 
 4. Read repo `AGENTS.md` (project conventions and constraints).
 

package/templates/vault/plan.md

@@ -0,0 +1,16 @@
+<!-- Reference shape for /grounder-plan. Not installed or filled by the CLI — slash commands embed this structure. -->
+
+# Plan: <title>
+
+## Goal
+…
+
+## Steps
+1. …
+2. …
+
+## Decisions / open questions
+- …
+
+## Status
+…