@agent-plan/core 0.2.19-next.9 → 0.2.19

package/dist/checklist.d.ts

@@ -0,0 +1,16 @@
+import type { ChecklistItem } from "./schema.js";
+/**
+ * Granular per-task checklist helpers. Each item has a stable unique `id`
+ * (the robust handle for add/remove/toggle) plus a progressive `number`
+ * (C1..Cn display label, renumbered on remove for readability). Selectors
+ * accept C{n} (e.g. C2), the item id, or a title (case-insensitive, first
+ * exact then partial match).
+ */
+export declare function findChecklistItem(items: ChecklistItem[], selector: string): ChecklistItem | undefined;
+/** Append a new item. number = max(existing)+1 (stable, never reused). Mutates nothing; returns the new item. */
+export declare function addChecklistItem(items: ChecklistItem[], taskId: string, title: string): ChecklistItem;
+/** Remove the matched item in place (splice) and renumber the rest 1..n. Returns the removed item, or undefined. */
+export declare function removeChecklistItem(items: ChecklistItem[], selector: string): ChecklistItem | undefined;
+/** Tick/untick the matched item in place. checked omitted → toggle. Returns the item, or undefined. */
+export declare function toggleChecklistItem(items: ChecklistItem[], selector: string, checked?: boolean): ChecklistItem | undefined;
+//# sourceMappingURL=checklist.d.ts.map

package/dist/checklist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checklist.d.ts","sourceRoot":"","sources":["../src/checklist.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;;GAMG;AAEH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAerG;AAED,iHAAiH;AACjH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAKrG;AAED,oHAAoH;AACpH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CASvG;AAED,uGAAuG;AACvG,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAK1H"}

package/dist/checklist.js

@@ -0,0 +1,52 @@
+import { createChecklistItemId } from "./naming.js";
+/**
+ * Granular per-task checklist helpers. Each item has a stable unique `id`
+ * (the robust handle for add/remove/toggle) plus a progressive `number`
+ * (C1..Cn display label, renumbered on remove for readability). Selectors
+ * accept C{n} (e.g. C2), the item id, or a title (case-insensitive, first
+ * exact then partial match).
+ */
+export function findChecklistItem(items, selector) {
+    const s = selector.trim();
+    if (!s)
+        return undefined;
+    const cMatch = /^C(\d+)$/i.exec(s);
+    if (cMatch) {
+        const n = parseInt(cMatch[1], 10);
+        return items.find((i) => i.number === n);
+    }
+    const byId = items.find((i) => i.id === s);
+    if (byId)
+        return byId;
+    const needle = s.toLowerCase();
+    return (items.find((i) => i.title.trim().toLowerCase() === needle) ??
+        items.find((i) => i.title.trim().toLowerCase().includes(needle)));
+}
+/** Append a new item. number = max(existing)+1 (stable, never reused). Mutates nothing; returns the new item. */
+export function addChecklistItem(items, taskId, title) {
+    const clean = title.trim();
+    const number = items.length === 0 ? 1 : Math.max(...items.map((i) => i.number)) + 1;
+    const id = createChecklistItemId(taskId, number, clean);
+    return { id, number, title: clean, checked: false };
+}
+/** Remove the matched item in place (splice) and renumber the rest 1..n. Returns the removed item, or undefined. */
+export function removeChecklistItem(items, selector) {
+    const found = findChecklistItem(items, selector);
+    if (!found)
+        return undefined;
+    const idx = items.findIndex((i) => i.id === found.id);
+    if (idx >= 0)
+        items.splice(idx, 1);
+    items.forEach((i, n) => {
+        i.number = n + 1;
+    });
+    return found;
+}
+/** Tick/untick the matched item in place. checked omitted → toggle. Returns the item, or undefined. */
+export function toggleChecklistItem(items, selector, checked) {
+    const found = findChecklistItem(items, selector);
+    if (!found)
+        return undefined;
+    found.checked = checked ?? !found.checked;
+    return found;
+}

package/dist/display-status.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Derived parent display-status layer.
+ *
+ * Parent entities (feature, phase) need a presentation-oriented summary of
+ * their children's workflow states that reads clearly in the Web UI, without
+ * overloading the canonical workflow statuses persisted in planner data.
+ *
+ * This module introduces two PARENT-ONLY derived presentation states:
+ * - `started`: the entity has clearly begun (historical progress exists) but
+ *   no child is active now, and the unfinished remainder is mixed or cannot
+ *   honestly collapse to one specific workflow label.
+ * - `closed`: every child is terminal, but outcomes are mixed (e.g.
+ *   `done + canceled`, `canceled + rejected`).
+ *
+ * These are NEVER persisted: they are computed on demand from children's
+ * canonical workflow statuses. The canonical workflow model
+ * (`planned | in-progress | waiting | blocked | deferred | done | canceled |
+ * rejected`) is unchanged.
+ */
+import type { TaskStatus, PhaseStatus } from "./schema.js";
+/**
+ * Canonical workflow status values used by tasks, phases, and features.
+ * Mirrors the union of TaskStatus and PhaseStatus used in the planner data.
+ */
+export type WorkflowStatus = "planned" | "in-progress" | "waiting" | "blocked" | "deferred" | "done" | "canceled" | "rejected";
+/**
+ * Display status adds parent-only presentation states on top of workflow
+ * statuses. Only parent entities (feature, phase) use the full union; leaf
+ * tasks always use plain WorkflowStatus.
+ */
+export type DisplayStatus = WorkflowStatus | "started" | "closed";
+/** Per-status counts for a set of children. */
+export interface StatusBreakdown {
+    planned: number;
+    inProgress: number;
+    waiting: number;
+    blocked: number;
+    deferred: number;
+    done: number;
+    canceled: number;
+    rejected: number;
+}
+/** Derived presentation snapshot for a parent entity. */
+export interface ParentDisplay {
+    /** Single presentation status for badges/summaries. */
+    displayStatus: DisplayStatus;
+    /** Counts of children per canonical workflow status. */
+    breakdown: StatusBreakdown;
+    /** True when at least one meaningful child is not `planned`
+     *  (i.e. the entity has clearly begun). */
+    hasStarted: boolean;
+    /** Total number of children (including canceled/rejected). */
+    totalChildren: number;
+    /** Meaningful children count (canceled/rejected excluded). */
+    meaningfulChildren: number;
+}
+/** Count children per canonical workflow status. Pure; does not mutate input. */
+export declare function countBreakdown(statuses: readonly WorkflowStatus[]): StatusBreakdown;
+/**
+ * Derive the parent display snapshot from its children's canonical statuses.
+ *
+ * Algorithm (locked by P039 accepted decisions):
+ *  1. If any meaningful child is active now → `in-progress`.
+ *  2. If every child is terminal:
+ *       - all `done` → `done`
+ *       - all `canceled` → `canceled`
+ *       - all `rejected` → `rejected`
+ *       - otherwise → `closed` (mixed terminal outcomes)
+ *  3. Compute `unfinished = meaningful ∩ OPEN`.
+ *       - homogeneous `waiting` → `waiting`
+ *       - homogeneous `blocked` → `blocked`
+ *       - homogeneous `deferred` → `deferred`
+ *  4. If all unfinished are `planned` and the entity has not started → `planned`.
+ *  5. Fallback → `started` (mixed non-active remainder, or planned with
+ *     historical progress).
+ *
+ * Edge cases:
+ *  - empty input → `planned` (a parent with no meaningful children yet reads
+ *    as not started; this is the least surprising default for empty phases).
+ *  - `meaningful` excludes `canceled` and `rejected` (terminal non-positive).
+ *  - `hasStarted = meaningful.some(s => s !== "planned")`.
+ *
+ * Pure and non-persisting. Never mutates the input array.
+ */
+export declare function deriveParentDisplay(childStatuses: readonly WorkflowStatus[]): ParentDisplay;
+/**
+ * Narrow an arbitrary canonical status string to a WorkflowStatus.
+ * Useful for adapters that hold the union of task/phase statuses.
+ * Returns `null` when the value is not a recognized workflow status.
+ */
+export declare function toWorkflowStatus(value: string): WorkflowStatus | null;
+/**
+ * Convert a canonical task/phase status into the workflow status union used
+ * by the display layer. Accepts the extra phase statuses and maps them:
+ * - `discovery` → `in-progress` (a phase in discovery is active work)
+ * - `draft` → `planned` (a draft phase has no tasks yet → not started)
+ */
+export declare function fromCanonicalStatus(status: TaskStatus | PhaseStatus): WorkflowStatus;
+//# sourceMappingURL=display-status.d.ts.map

package/dist/display-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display-status.d.ts","sourceRoot":"","sources":["../src/display-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,aAAa,GACb,SAAS,GACT,SAAS,GACT,UAAU,GACV,MAAM,GACN,UAAU,GACV,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElE,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,aAAa,EAAE,aAAa,CAAC;IAC7B,wDAAwD;IACxD,SAAS,EAAE,eAAe,CAAC;IAC3B;+CAC2C;IAC3C,UAAU,EAAE,OAAO,CAAC;IACpB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAMD,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,eAAe,CAkBnF;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,SAAS,cAAc,EAAE,GAAG,aAAa,CAiE3F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAcrE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,cAAc,CAIpF"}

package/dist/display-status.js

@@ -0,0 +1,176 @@
+/**
+ * Derived parent display-status layer.
+ *
+ * Parent entities (feature, phase) need a presentation-oriented summary of
+ * their children's workflow states that reads clearly in the Web UI, without
+ * overloading the canonical workflow statuses persisted in planner data.
+ *
+ * This module introduces two PARENT-ONLY derived presentation states:
+ * - `started`: the entity has clearly begun (historical progress exists) but
+ *   no child is active now, and the unfinished remainder is mixed or cannot
+ *   honestly collapse to one specific workflow label.
+ * - `closed`: every child is terminal, but outcomes are mixed (e.g.
+ *   `done + canceled`, `canceled + rejected`).
+ *
+ * These are NEVER persisted: they are computed on demand from children's
+ * canonical workflow statuses. The canonical workflow model
+ * (`planned | in-progress | waiting | blocked | deferred | done | canceled |
+ * rejected`) is unchanged.
+ */
+const ACTIVE = new Set(["in-progress"]);
+const OPEN = new Set(["planned", "waiting", "blocked", "deferred"]);
+const TERMINAL = new Set(["done", "canceled", "rejected"]);
+/** Count children per canonical workflow status. Pure; does not mutate input. */
+export function countBreakdown(statuses) {
+    const breakdown = {
+        planned: 0, inProgress: 0, waiting: 0, blocked: 0,
+        deferred: 0, done: 0, canceled: 0, rejected: 0,
+    };
+    for (const s of statuses) {
+        switch (s) {
+            case "planned":
+                breakdown.planned++;
+                break;
+            case "in-progress":
+                breakdown.inProgress++;
+                break;
+            case "waiting":
+                breakdown.waiting++;
+                break;
+            case "blocked":
+                breakdown.blocked++;
+                break;
+            case "deferred":
+                breakdown.deferred++;
+                break;
+            case "done":
+                breakdown.done++;
+                break;
+            case "canceled":
+                breakdown.canceled++;
+                break;
+            case "rejected":
+                breakdown.rejected++;
+                break;
+        }
+    }
+    return breakdown;
+}
+function emptyBreakdown() {
+    return { planned: 0, inProgress: 0, waiting: 0, blocked: 0, deferred: 0, done: 0, canceled: 0, rejected: 0 };
+}
+/**
+ * Derive the parent display snapshot from its children's canonical statuses.
+ *
+ * Algorithm (locked by P039 accepted decisions):
+ *  1. If any meaningful child is active now → `in-progress`.
+ *  2. If every child is terminal:
+ *       - all `done` → `done`
+ *       - all `canceled` → `canceled`
+ *       - all `rejected` → `rejected`
+ *       - otherwise → `closed` (mixed terminal outcomes)
+ *  3. Compute `unfinished = meaningful ∩ OPEN`.
+ *       - homogeneous `waiting` → `waiting`
+ *       - homogeneous `blocked` → `blocked`
+ *       - homogeneous `deferred` → `deferred`
+ *  4. If all unfinished are `planned` and the entity has not started → `planned`.
+ *  5. Fallback → `started` (mixed non-active remainder, or planned with
+ *     historical progress).
+ *
+ * Edge cases:
+ *  - empty input → `planned` (a parent with no meaningful children yet reads
+ *    as not started; this is the least surprising default for empty phases).
+ *  - `meaningful` excludes `canceled` and `rejected` (terminal non-positive).
+ *  - `hasStarted = meaningful.some(s => s !== "planned")`.
+ *
+ * Pure and non-persisting. Never mutates the input array.
+ */
+export function deriveParentDisplay(childStatuses) {
+    const statuses = childStatuses;
+    const breakdown = countBreakdown(statuses);
+    const totalChildren = statuses.length;
+    if (totalChildren === 0) {
+        return {
+            displayStatus: "planned",
+            breakdown: emptyBreakdown(),
+            hasStarted: false,
+            totalChildren: 0,
+            meaningfulChildren: 0,
+        };
+    }
+    // Meaningful set excludes terminal non-positive outcomes.
+    const meaningful = statuses.filter((s) => s !== "canceled" && s !== "rejected");
+    const meaningfulChildren = meaningful.length;
+    const hasStarted = meaningful.some((s) => s !== "planned");
+    // 1. Active child work exists now.
+    if (meaningful.some((s) => ACTIVE.has(s))) {
+        return { displayStatus: "in-progress", breakdown, hasStarted, totalChildren, meaningfulChildren };
+    }
+    // 2. All children are terminal.
+    if (statuses.every((s) => TERMINAL.has(s))) {
+        if (statuses.every((s) => s === "done")) {
+            return { displayStatus: "done", breakdown, hasStarted, totalChildren, meaningfulChildren };
+        }
+        if (statuses.every((s) => s === "canceled")) {
+            return { displayStatus: "canceled", breakdown, hasStarted, totalChildren, meaningfulChildren };
+        }
+        if (statuses.every((s) => s === "rejected")) {
+            return { displayStatus: "rejected", breakdown, hasStarted, totalChildren, meaningfulChildren };
+        }
+        return { displayStatus: "closed", breakdown, hasStarted, totalChildren, meaningfulChildren };
+    }
+    // 3. Unfinished meaningful remainder.
+    const unfinished = meaningful.filter((s) => OPEN.has(s));
+    const allWaiting = unfinished.length > 0 && unfinished.every((s) => s === "waiting");
+    if (allWaiting) {
+        return { displayStatus: "waiting", breakdown, hasStarted, totalChildren, meaningfulChildren };
+    }
+    const allBlocked = unfinished.length > 0 && unfinished.every((s) => s === "blocked");
+    if (allBlocked) {
+        return { displayStatus: "blocked", breakdown, hasStarted, totalChildren, meaningfulChildren };
+    }
+    const allDeferred = unfinished.length > 0 && unfinished.every((s) => s === "deferred");
+    if (allDeferred) {
+        return { displayStatus: "deferred", breakdown, hasStarted, totalChildren, meaningfulChildren };
+    }
+    // 4. All unfinished are planned and the entity has never started.
+    const allPlanned = unfinished.length > 0 && unfinished.every((s) => s === "planned");
+    if (allPlanned && !hasStarted) {
+        return { displayStatus: "planned", breakdown, hasStarted, totalChildren, meaningfulChildren };
+    }
+    // 5. Fallback: started (mixed non-active remainder, or planned with history).
+    return { displayStatus: "started", breakdown, hasStarted, totalChildren, meaningfulChildren };
+}
+/**
+ * Narrow an arbitrary canonical status string to a WorkflowStatus.
+ * Useful for adapters that hold the union of task/phase statuses.
+ * Returns `null` when the value is not a recognized workflow status.
+ */
+export function toWorkflowStatus(value) {
+    switch (value) {
+        case "planned":
+        case "in-progress":
+        case "waiting":
+        case "blocked":
+        case "deferred":
+        case "done":
+        case "canceled":
+        case "rejected":
+            return value;
+        default:
+            return null;
+    }
+}
+/**
+ * Convert a canonical task/phase status into the workflow status union used
+ * by the display layer. Accepts the extra phase statuses and maps them:
+ * - `discovery` → `in-progress` (a phase in discovery is active work)
+ * - `draft` → `planned` (a draft phase has no tasks yet → not started)
+ */
+export function fromCanonicalStatus(status) {
+    if (status === "discovery")
+        return "in-progress";
+    if (status === "draft")
+        return "planned";
+    return status;
+}

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 export * from "./naming.js";
 export * from "./refs.js";
 export * from "./schema.js";
+export * from "./checklist.js";
 export * from "./recap.js";
-export { PlanStore, PlanStoreError, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, type PhaseHandoffSummary } from "./plan-store.js";
+export * from "./display-status.js";
+export * from "./task-context.js";
+export * from "./task-selection.js";
+export { PlanStore, PlanStoreError, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock, type PhaseHandoffSummary, type OrphanPhaseSummary } from "./plan-store.js";
 export { PlanRenderer } from "./renderer.js";
 export { ExportService } from "./export-service.js";
 export type { CodebaseProfile, ResumeFocus, ActivityEntry, ActivityLog, AmbientFacts } from "./schema.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtL,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,uBAAuB,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC/M,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,7 +1,11 @@
 export * from "./naming.js";
 export * from "./refs.js";
 export * from "./schema.js";
+export * from "./checklist.js";
 export * from "./recap.js";
+export * from "./display-status.js";
+export * from "./task-context.js";
+export * from "./task-selection.js";
 export { PlanStore, PlanStoreError, setWriteBusyHook, setWriteNotifyHook, migrateToUuids, migrateToGlobalSequence, withFeatureLock } from "./plan-store.js";
 export { PlanRenderer } from "./renderer.js";
 export { ExportService } from "./export-service.js";

package/dist/naming.d.ts

@@ -3,10 +3,27 @@
 export declare const CROCKFORD_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
 export declare const SHORT_ID_LENGTH = 5;
 export declare const SHORT_ID_PATTERN: RegExp;
+/** Loose UUID v4 regex (case-insensitive). Used for input sanity checks. */
+export declare const UUID_PATTERN: RegExp;
+export declare function isUuid(value: unknown): value is string;
+/** Belt-and-suspenders validation: a resolved ref must be a real UUID and the
+ *  target must still exist in the store before we allocate numbers or write.
+ *  Used by adapter create tools (task_create, phase_create). */
+export declare function validateResolvedTarget<T extends {
+    id: string;
+}>(kind: "feature" | "phase", resolvedId: string, loader: () => Promise<T | undefined>): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;
 /** Generate a globally-unique short id (5 chars, Crockford Base32, e.g. `UUXD1`-style
- *  but without 0/1/I/O). Retries until the id is not in `existing` (project-scoped
- *  collision guard). Throws only in the impossible saturation case (~50 retries). */
-export declare function createShortId(existing?: Set<string>): string;
+ *  but without 0/1/I/O). If `seed` is provided, the id is derived deterministically
+ *  from a stable hash of the seed so two worktrees starting from the same commit
+ *  produce identical shortIds for the same entity. Retries until the id is not in
+ *  `existing` (project-scoped collision guard). Throws only in the impossible
+ *  saturation case (~50 retries). */
+export declare function createShortId(existing?: Set<string>, seed?: string): string;
 export declare function normalizeSlug(input: string): string;
 /** Normalize, truncate to maxLen, and strip dangling dashes so the result
  * always satisfies SlugSchema (/^[a-z0-9]+(?:-[a-z0-9]+)*$/). Returns fallback
@@ -39,4 +56,5 @@ export declare function createRequirementId(): string;
 export declare function createMacroTaskId(): string;
 export declare function createFeatureId(): string;
 export declare function createChecklistItemId(taskId: string, number: number, title: string): string;
+export declare function createStatusLogEntryId(): string;
 //# sourceMappingURL=naming.d.ts.map

package/dist/naming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAKA;iFACiF;AACjF,eAAO,MAAM,kBAAkB,qCAAqC,CAAC;AAErE,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,gBAAgB,QAAkB,CAAC;AAEhD;;qFAEqF;AACrF,wBAAgB,aAAa,CAAC,QAAQ,GAAE,GAAG,CAAC,MAAM,CAAa,GAAG,MAAM,CAUvE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;8BAI8B;AAC9B,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAK,EAAE,QAAQ,SAAa,GAAG,MAAM,CAGnF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;iBAEiB;AACjB,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlF;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,EAChD,QAAQ,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,GACzC,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtF;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3F"}
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../src/naming.ts"],"names":[],"mappings":"AAKA;iFACiF;AACjF,eAAO,MAAM,kBAAkB,qCAAqC,CAAC;AAErE,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,gBAAgB,QAAkB,CAAC;AAEhD,4EAA4E;AAC5E,eAAO,MAAM,YAAY,QAAoE,CAAC;AAE9F,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEtD;AAED;;gEAEgE;AAChE,wBAAsB,sBAAsB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EACnE,IAAI,EAAE,SAAS,GAAG,OAAO,EACzB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GACnC,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAStD;AAGD;;;;;qCAKqC;AACrC,wBAAgB,aAAa,CAAC,QAAQ,GAAE,GAAG,CAAC,MAAM,CAAa,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CA2BtF;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;8BAI8B;AAC9B,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAK,EAAE,QAAQ,SAAa,GAAG,MAAM,CAGnF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;iBAEiB;AACjB,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlF;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,EAChD,QAAQ,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,GACzC,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtF;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3F;AAED,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C"}

package/dist/naming.js

@@ -6,10 +6,49 @@ const MULTI_DASH_PATTERN = /-+/g;
 export const CROCKFORD_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
 export const SHORT_ID_LENGTH = 5;
 export const SHORT_ID_PATTERN = /^[A-Z2-9]{5}$/;
+/** Loose UUID v4 regex (case-insensitive). Used for input sanity checks. */
+export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function isUuid(value) {
+    return typeof value === "string" && UUID_PATTERN.test(value);
+}
+/** Belt-and-suspenders validation: a resolved ref must be a real UUID and the
+ *  target must still exist in the store before we allocate numbers or write.
+ *  Used by adapter create tools (task_create, phase_create). */
+export async function validateResolvedTarget(kind, resolvedId, loader) {
+    if (!isUuid(resolvedId)) {
+        return { ok: false, error: `Resolved ${kind} id is not a valid UUID: ${resolvedId}` };
+    }
+    const target = await loader();
+    if (!target) {
+        return { ok: false, error: `Resolved ${kind} ${resolvedId} no longer exists. Refusing to create child.` };
+    }
+    return { ok: true };
+}
 /** Generate a globally-unique short id (5 chars, Crockford Base32, e.g. `UUXD1`-style
- *  but without 0/1/I/O). Retries until the id is not in `existing` (project-scoped
- *  collision guard). Throws only in the impossible saturation case (~50 retries). */
-export function createShortId(existing = new Set()) {
+ *  but without 0/1/I/O). If `seed` is provided, the id is derived deterministically
+ *  from a stable hash of the seed so two worktrees starting from the same commit
+ *  produce identical shortIds for the same entity. Retries until the id is not in
+ *  `existing` (project-scoped collision guard). Throws only in the impossible
+ *  saturation case (~50 retries). */
+export function createShortId(existing = new Set(), seed) {
+    if (seed) {
+        // Stable string hash -> Crockford encoding.
+        let hash = 0;
+        for (const c of seed) {
+            hash = ((hash << 5) - hash + c.charCodeAt(0)) | 0;
+        }
+        const base = Math.abs(hash);
+        for (let offset = 0; offset < 64; offset += 1) {
+            let id = "";
+            let value = base + offset;
+            for (let i = 0; i < SHORT_ID_LENGTH; i += 1) {
+                id = CROCKFORD_ALPHABET[value % CROCKFORD_ALPHABET.length] + id;
+                value = Math.floor(value / CROCKFORD_ALPHABET.length);
+            }
+            if (!existing.has(id))
+                return id;
+        }
+    }
     const max = CROCKFORD_ALPHABET.length;
     for (let attempt = 0; attempt < 64; attempt += 1) {
         let id = "";
@@ -86,3 +125,6 @@ export function createFeatureId() {
 export function createChecklistItemId(taskId, number, title) {
     return `${taskId}-check-${formatThreeDigitNumber(number)}-${normalizeSlug(title)}`;
 }
+export function createStatusLogEntryId() {
+    return randomUUID();
+}