@anthropologies/claudestory 0.1.8 → 0.1.9

package/dist/index.d.ts

@@ -102,6 +102,33 @@ declare const IssueSchema: z.ZodObject<{
 }, z.ZodTypeAny, "passthrough">>;
 type Issue = z.infer<typeof IssueSchema>;
 
+declare const NoteSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, unknown>;
+    content: z.ZodEffects<z.ZodString, string, string>;
+    tags: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>;
+    status: z.ZodEnum<["active", "archived"]>;
+    createdDate: z.ZodEffects<z.ZodString, string, string>;
+    updatedDate: z.ZodEffects<z.ZodString, string, string>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodString;
+    title: z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, unknown>;
+    content: z.ZodEffects<z.ZodString, string, string>;
+    tags: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>;
+    status: z.ZodEnum<["active", "archived"]>;
+    createdDate: z.ZodEffects<z.ZodString, string, string>;
+    updatedDate: z.ZodEffects<z.ZodString, string, string>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodString;
+    title: z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, unknown>;
+    content: z.ZodEffects<z.ZodString, string, string>;
+    tags: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>;
+    status: z.ZodEnum<["active", "archived"]>;
+    createdDate: z.ZodEffects<z.ZodString, string, string>;
+    updatedDate: z.ZodEffects<z.ZodString, string, string>;
+}, z.ZodTypeAny, "passthrough">>;
+type Note = z.infer<typeof NoteSchema>;
+
 declare const BlockerSchema: z.ZodObject<{
     name: z.ZodString;
     cleared: z.ZodOptional<z.ZodBoolean>;
@@ -378,6 +405,10 @@ declare const ISSUE_STATUSES: readonly ["open", "inprogress", "resolved"];
 type IssueStatus = (typeof ISSUE_STATUSES)[number];
 declare const ISSUE_SEVERITIES: readonly ["critical", "high", "medium", "low"];
 type IssueSeverity = (typeof ISSUE_SEVERITIES)[number];
+declare const NOTE_STATUSES: readonly ["active", "archived"];
+type NoteStatus = (typeof NOTE_STATUSES)[number];
+declare const NOTE_ID_REGEX: RegExp;
+declare const NoteIdSchema: z.ZodString;
 declare const OUTPUT_FORMATS: readonly ["json", "md"];
 type OutputFormat = (typeof OUTPUT_FORMATS)[number];
 declare const ERROR_CODES: readonly ["not_found", "validation_failed", "io_error", "project_corrupt", "invalid_input", "conflict", "version_mismatch"];
@@ -395,6 +426,7 @@ type PhaseStatus = "notstarted" | "inprogress" | "complete";
 declare class ProjectState {
     readonly tickets: readonly Ticket[];
     readonly issues: readonly Issue[];
+    readonly notes: readonly Note[];
     readonly roadmap: Readonly<Roadmap>;
     readonly config: Readonly<Config>;
     readonly handoverFilenames: readonly string[];
@@ -407,14 +439,18 @@ declare class ProjectState {
     private readonly reverseBlocksMap;
     private readonly ticketsByID;
     private readonly issuesByID;
+    private readonly notesByID;
     readonly totalTicketCount: number;
     readonly openTicketCount: number;
     readonly completeTicketCount: number;
     readonly openIssueCount: number;
     readonly issuesBySeverity: ReadonlyMap<IssueSeverity, number>;
+    readonly activeNoteCount: number;
+    readonly archivedNoteCount: number;
     constructor(input: {
         tickets: Ticket[];
         issues: Issue[];
+        notes: Note[];
         roadmap: Roadmap;
         config: Config;
         handoverFilenames: string[];
@@ -435,6 +471,7 @@ declare class ProjectState {
     get blockedCount(): number;
     ticketByID(id: string): Ticket | undefined;
     issueByID(id: string): Issue | undefined;
+    noteByID(id: string): Note | undefined;
     /** IDs of tickets that list `ticketId` in their blockedBy. */
     ticketsBlocking(ticketId: string): string[];
     /** IDs of tickets that have `ticketId` as their parentTicket. */
@@ -518,6 +555,13 @@ declare function deleteTicket(id: string, root: string, options?: {
     force?: boolean;
 }): Promise<void>;
 declare function deleteIssue(id: string, root: string): Promise<void>;
+/**
+ * Writes a note file WITHOUT acquiring the project lock.
+ * Use inside withProjectLock when the lock is already held.
+ */
+declare function writeNoteUnlocked(note: Note, root: string): Promise<void>;
+declare function writeNote(note: Note, root: string): Promise<void>;
+declare function deleteNote(id: string, root: string): Promise<void>;
 interface WithProjectLockOptions {
     strict?: boolean;
 }
@@ -618,6 +662,25 @@ interface NextTicketEmpty {
     readonly kind: "empty_project";
 }
 type NextTicketOutcome = NextTicketResult | NextTicketAllComplete | NextTicketAllBlocked | NextTicketEmpty;
+interface NextTicketCandidate {
+    readonly ticket: Ticket;
+    readonly unblockImpact: UnblockImpact;
+    readonly umbrellaProgress: UmbrellaProgress | null;
+}
+interface SkippedBlockedPhase {
+    readonly phaseId: string;
+    readonly blockedCount: number;
+}
+interface NextTicketsResult {
+    readonly kind: "found";
+    readonly candidates: readonly NextTicketCandidate[];
+    readonly skippedBlockedPhases: readonly SkippedBlockedPhase[];
+}
+interface NextTicketsAllBlocked {
+    readonly kind: "all_blocked";
+    readonly phases: readonly SkippedBlockedPhase[];
+}
+type NextTicketsOutcome = NextTicketsResult | NextTicketsAllBlocked | NextTicketAllComplete | NextTicketEmpty;
 interface PhaseWithStatus {
     readonly phase: Phase;
     readonly status: PhaseStatus;
@@ -629,6 +692,12 @@ interface PhaseWithStatus {
  * Returns discriminated outcome for exhaustive handling.
  */
 declare function nextTicket(state: ProjectState): NextTicketOutcome;
+/**
+ * Up to `count` unblocked leaf tickets across all non-complete phases
+ * (roadmap order). Unlike nextTicket, continues past fully-blocked phases
+ * and collects multiple candidates within the same phase.
+ */
+declare function nextTickets(state: ProjectState, count: number): NextTicketsOutcome;
 /**
  * All currently blocked incomplete leaf tickets.
  */
@@ -656,6 +725,35 @@ declare function phasesWithStatus(state: ProjectState): readonly PhaseWithStatus
  * Legacy: cleared boolean. New: clearedDate non-null.
  */
 declare function isBlockerCleared(blocker: Blocker): boolean;
+/**
+ * All descendant leaf tickets of an umbrella (recursive).
+ * Public wrapper around the private cycle-safe helper.
+ */
+declare function descendantLeaves(ticketId: string, state: ProjectState): Ticket[];
+
+/**
+ * Context-aware work recommendation engine.
+ *
+ * Unlike nextTicket (queue-based, phase order), recommend considers the full
+ * project state and suggests a ranked list mixing tickets and issues, each
+ * with a human-readable rationale.
+ */
+
+type RecommendCategory = "validation_errors" | "critical_issue" | "inprogress_ticket" | "high_impact_unblock" | "near_complete_umbrella" | "phase_momentum" | "quick_win" | "open_issue";
+type RecommendItemKind = "ticket" | "issue" | "action";
+interface Recommendation {
+    readonly id: string;
+    readonly kind: RecommendItemKind;
+    readonly title: string;
+    readonly category: RecommendCategory;
+    readonly reason: string;
+    readonly score: number;
+}
+interface RecommendResult {
+    readonly recommendations: readonly Recommendation[];
+    readonly totalCandidates: number;
+}
+declare function recommend(state: ProjectState, count: number): RecommendResult;
 
 /**
  * Next ticket ID: scan existing IDs, find max numeric part, return T-(max+1).
@@ -668,6 +766,11 @@ declare function nextTicketID(tickets: readonly Ticket[]): string;
  * Zero-padded to 3 digits minimum.
  */
 declare function nextIssueID(issues: readonly Issue[]): string;
+/**
+ * Next note ID: scan existing IDs, find max numeric part, return N-(max+1).
+ * Zero-padded to 3 digits minimum.
+ */
+declare function nextNoteID(notes: readonly Note[]): string;
 /**
  * Next order value for a phase: max leaf ticket order + 10, or 10 if empty.
  */
@@ -1018,6 +1121,31 @@ declare const SnapshotV1Schema: z.ZodObject<{
         assignedTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         lastModifiedBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.ZodTypeAny, "passthrough">>, "many">;
+    notes: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, unknown>;
+        content: z.ZodEffects<z.ZodString, string, string>;
+        tags: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>;
+        status: z.ZodEnum<["active", "archived"]>;
+        createdDate: z.ZodEffects<z.ZodString, string, string>;
+        updatedDate: z.ZodEffects<z.ZodString, string, string>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        title: z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, unknown>;
+        content: z.ZodEffects<z.ZodString, string, string>;
+        tags: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>;
+        status: z.ZodEnum<["active", "archived"]>;
+        createdDate: z.ZodEffects<z.ZodString, string, string>;
+        updatedDate: z.ZodEffects<z.ZodString, string, string>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        title: z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, unknown>;
+        content: z.ZodEffects<z.ZodString, string, string>;
+        tags: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>;
+        status: z.ZodEnum<["active", "archived"]>;
+        createdDate: z.ZodEffects<z.ZodString, string, string>;
+        updatedDate: z.ZodEffects<z.ZodString, string, string>;
+    }, z.ZodTypeAny, "passthrough">>, "many">>>;
     warnings: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodString;
         file: z.ZodString;
@@ -1088,6 +1216,15 @@ declare const SnapshotV1Schema: z.ZodObject<{
     };
     version: 1;
     project: string;
+    notes: z.objectOutputType<{
+        id: z.ZodString;
+        title: z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, unknown>;
+        content: z.ZodEffects<z.ZodString, string, string>;
+        tags: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>;
+        status: z.ZodEnum<["active", "archived"]>;
+        createdDate: z.ZodEffects<z.ZodString, string, string>;
+        updatedDate: z.ZodEffects<z.ZodString, string, string>;
+    }, z.ZodTypeAny, "passthrough">[];
     createdAt: string;
     config: {
         type: string;
@@ -1188,6 +1325,15 @@ declare const SnapshotV1Schema: z.ZodObject<{
     } & {
         [k: string]: unknown;
     };
+    notes?: z.objectInputType<{
+        id: z.ZodString;
+        title: z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, unknown>;
+        content: z.ZodEffects<z.ZodString, string, string>;
+        tags: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>;
+        status: z.ZodEnum<["active", "archived"]>;
+        createdDate: z.ZodEffects<z.ZodString, string, string>;
+        updatedDate: z.ZodEffects<z.ZodString, string, string>;
+    }, z.ZodTypeAny, "passthrough">[] | undefined;
     warnings?: {
         message: string;
         type: string;
@@ -1232,6 +1378,15 @@ interface PhaseChange {
     from: string;
     to: string;
 }
+interface ContentChange {
+    id: string;
+    title: string;
+}
+interface NoteChange {
+    id: string;
+    title: string | null;
+    changedFields: string[];
+}
 interface SnapshotDiff {
     tickets: {
         added: Array<{
@@ -1243,6 +1398,7 @@ interface SnapshotDiff {
             title: string;
         }>;
         statusChanged: TicketChange[];
+        descriptionChanged: ContentChange[];
     };
     issues: {
         added: Array<{
@@ -1254,6 +1410,7 @@ interface SnapshotDiff {
             title: string;
         }>;
         statusChanged: IssueChange[];
+        impactChanged: ContentChange[];
     };
     blockers: {
         added: string[];
@@ -1270,6 +1427,17 @@ interface SnapshotDiff {
         }>;
         statusChanged: PhaseChange[];
     };
+    notes: {
+        added: Array<{
+            id: string;
+            title: string | null;
+        }>;
+        removed: Array<{
+            id: string;
+            title: string | null;
+        }>;
+        updated: NoteChange[];
+    };
 }
 interface RecapResult {
     snapshot: {
@@ -1374,5 +1542,6 @@ declare function formatSnapshotResult(result: {
 }, format: OutputFormat): string;
 declare function formatRecap(recap: RecapResult, state: ProjectState, format: OutputFormat): string;
 declare function formatExport(state: ProjectState, mode: "all" | "phase", phaseId: string | null, format: OutputFormat): string;
+declare function formatRecommendations(result: RecommendResult, format: OutputFormat): string;
 
-export { type Blocker, BlockerSchema, CURRENT_SCHEMA_VERSION, type Config, ConfigSchema, DATE_REGEX, DateSchema, ERROR_CODES, type ErrorCode, type ErrorEnvelope, ExitCode, type ExitCodeValue, type Features, FeaturesSchema, INTEGRITY_WARNING_TYPES, ISSUE_ID_REGEX, ISSUE_SEVERITIES, ISSUE_STATUSES, type InitOptions, type InitResult, type Issue, IssueIdSchema, IssueSchema, type IssueSeverity, type IssueStatus, type LoadOptions, type LoadResult, type LoadWarning, type LoadWarningType, type NextTicketAllBlocked, type NextTicketAllComplete, type NextTicketEmpty, type NextTicketOutcome, type NextTicketResult, OUTPUT_FORMATS, type OutputFormat, type PartialEnvelope, type Phase, PhaseSchema, type PhaseStatus, type PhaseWithStatus, ProjectLoaderError, ProjectState, type RecapResult, type Roadmap, RoadmapSchema, type SnapshotDiff, type SnapshotV1, SnapshotV1Schema, type SuccessEnvelope, TICKET_ID_REGEX, TICKET_STATUSES, TICKET_TYPES, type Ticket, TicketIdSchema, TicketSchema, type TicketStatus, type TicketType, type UmbrellaProgress, type UnblockImpact, type ValidationFinding, type ValidationLevel, type ValidationResult, type WithProjectLockOptions, atomicWrite, blockedTickets, buildRecap, currentPhase, deleteIssue, deleteTicket, diffStates, discoverProjectRoot, errorEnvelope, escapeMarkdownInline, extractHandoverDate, fencedBlock, formatBlockedTickets, formatBlockerList, formatError, formatExport, formatHandoverContent, formatHandoverCreateResult, formatHandoverList, formatInitResult, formatIssue, formatIssueList, formatNextTicketOutcome, formatPhaseList, formatPhaseTickets, formatRecap, formatSnapshotResult, formatStatus, formatTicket, formatTicketList, formatValidation, guardPath, initProject, isBlockerCleared, listHandovers, loadLatestSnapshot, loadProject, mergeValidation, nextIssueID, nextOrder, nextTicket, nextTicketID, partialEnvelope, phasesWithStatus, readHandover, runTransaction, runTransactionUnlocked, saveSnapshot, serializeJSON, sortKeysDeep, successEnvelope, ticketsUnblockedBy, umbrellaProgress, validateProject, withProjectLock, writeConfig, writeIssue, writeIssueUnlocked, writeRoadmap, writeRoadmapUnlocked, writeTicket, writeTicketUnlocked };
+export { type Blocker, BlockerSchema, CURRENT_SCHEMA_VERSION, type Config, ConfigSchema, DATE_REGEX, DateSchema, ERROR_CODES, type ErrorCode, type ErrorEnvelope, ExitCode, type ExitCodeValue, type Features, FeaturesSchema, INTEGRITY_WARNING_TYPES, ISSUE_ID_REGEX, ISSUE_SEVERITIES, ISSUE_STATUSES, type InitOptions, type InitResult, type Issue, IssueIdSchema, IssueSchema, type IssueSeverity, type IssueStatus, type LoadOptions, type LoadResult, type LoadWarning, type LoadWarningType, NOTE_ID_REGEX, NOTE_STATUSES, type NextTicketAllBlocked, type NextTicketAllComplete, type NextTicketEmpty, type NextTicketOutcome, type NextTicketResult, type Note, NoteIdSchema, NoteSchema, type NoteStatus, OUTPUT_FORMATS, type OutputFormat, type PartialEnvelope, type Phase, PhaseSchema, type PhaseStatus, type PhaseWithStatus, ProjectLoaderError, ProjectState, type RecapResult, type RecommendCategory, type RecommendItemKind, type RecommendResult, type Recommendation, type Roadmap, RoadmapSchema, type SnapshotDiff, type SnapshotV1, SnapshotV1Schema, type SuccessEnvelope, TICKET_ID_REGEX, TICKET_STATUSES, TICKET_TYPES, type Ticket, TicketIdSchema, TicketSchema, type TicketStatus, type TicketType, type UmbrellaProgress, type UnblockImpact, type ValidationFinding, type ValidationLevel, type ValidationResult, type WithProjectLockOptions, atomicWrite, blockedTickets, buildRecap, currentPhase, deleteIssue, deleteNote, deleteTicket, descendantLeaves, diffStates, discoverProjectRoot, errorEnvelope, escapeMarkdownInline, extractHandoverDate, fencedBlock, formatBlockedTickets, formatBlockerList, formatError, formatExport, formatHandoverContent, formatHandoverCreateResult, formatHandoverList, formatInitResult, formatIssue, formatIssueList, formatNextTicketOutcome, formatPhaseList, formatPhaseTickets, formatRecap, formatRecommendations, formatSnapshotResult, formatStatus, formatTicket, formatTicketList, formatValidation, guardPath, initProject, isBlockerCleared, listHandovers, loadLatestSnapshot, loadProject, mergeValidation, nextIssueID, nextNoteID, nextOrder, nextTicket, nextTicketID, nextTickets, partialEnvelope, phasesWithStatus, readHandover, recommend, runTransaction, runTransactionUnlocked, saveSnapshot, serializeJSON, sortKeysDeep, successEnvelope, ticketsUnblockedBy, umbrellaProgress, validateProject, withProjectLock, writeConfig, writeIssue, writeIssueUnlocked, writeNote, writeNoteUnlocked, writeRoadmap, writeRoadmapUnlocked, writeTicket, writeTicketUnlocked };