crewly 1.20.288 → 1.20.290

package/dist/backend/backend/src/services/project-tickets/ticket-hygiene.js

@@ -0,0 +1,256 @@
+/**
+ * Ticket hygiene, pure half: when is a ticket stale, which stale tickets go to
+ * which lead today, and the brief that lead receives.
+ *
+ * Kept free of I/O so the thresholds, the cooldown and the batching are easy to
+ * test; {@link ./ticket-hygiene.service} does the reading and writing.
+ *
+ * @module services/project-tickets/ticket-hygiene
+ */
+import { ORCHESTRATOR_SESSION_NAME, TICKET_HYGIENE_CONSTANTS } from '../../constants.js';
+import { getTeamLeads } from '../../utils/team.utils.js';
+const C = TICKET_HYGIENE_CONSTANTS;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Statuses of a ticket that still counts as open work. */
+export const OPEN_TICKET_STATUSES = new Set(['backlog', 'ready', 'in_progress', 'review']);
+/** Labels that say "leave this alone for now" (the autopilot's park / owner-wait labels). */
+const QUIET_LABELS = new Set(['parked', 'deferred', 'needs-owner']);
+/**
+ * The days of silence after which a ticket of this status is stale.
+ *
+ * @param status - Ticket status
+ * @returns Days, or null when the status is not open
+ */
+export function staleThresholdDays(status) {
+    if (status === 'in_progress' || status === 'review')
+        return C.STALE_ACTIVE_DAYS;
+    if (status === 'ready' || status === 'backlog')
+        return C.STALE_IDLE_DAYS;
+    return null;
+}
+/**
+ * The time of a ticket's last real activity: the later of `updatedAt` and its
+ * newest Log line, ignoring lines the hygiene sweep wrote itself (a flag the
+ * sweep adds is not someone working on the ticket).
+ *
+ * @param t - Ticket
+ * @returns Epoch ms (0 when nothing parses)
+ */
+export function ticketLastActivityMs(t) {
+    let best = Date.parse(t.updatedAt);
+    if (!Number.isFinite(best))
+        best = Date.parse(t.createdAt);
+    if (!Number.isFinite(best))
+        best = 0;
+    for (const line of t.log ?? []) {
+        const m = /^(\S+) · ([^·]+?) · /.exec(line);
+        if (!m || m[2] === C.ACTOR)
+            continue;
+        const at = Date.parse(m[1]);
+        if (Number.isFinite(at) && at > best)
+            best = at;
+    }
+    return best;
+}
+/**
+ * Whether a ticket is stale right now.
+ *
+ * Not stale: closed tickets, tickets labelled parked / deferred / needs-owner,
+ * tickets deferred to a later date, and a `review` ticket that waits for the
+ * owner (`ownerReview`) — nobody on the team can decide that one.
+ *
+ * @param t - Ticket
+ * @param nowMs - Clock
+ * @returns Staleness
+ */
+export function ticketStaleness(t, nowMs) {
+    const lastMs = ticketLastActivityMs(t);
+    const thresholdDays = staleThresholdDays(t.status);
+    const idleDays = lastMs > 0 ? Math.max(0, Math.floor((nowMs - lastMs) / DAY_MS)) : 0;
+    const base = { idleDays, lastActivityAt: new Date(lastMs).toISOString(), thresholdDays };
+    if (thresholdDays === null || lastMs === 0)
+        return { ...base, stale: false };
+    if ((t.labels ?? []).some((l) => QUIET_LABELS.has(l)))
+        return { ...base, stale: false };
+    if (t.status === 'review' && t.ownerReview)
+        return { ...base, stale: false };
+    if (t.deferUntil) {
+        const until = Date.parse(t.deferUntil);
+        if (Number.isFinite(until) && until > nowMs)
+            return { ...base, stale: false };
+    }
+    return { ...base, stale: nowMs - lastMs >= thresholdDays * DAY_MS };
+}
+/**
+ * Whether a name looks like an agent session (`<team>-<name>-<8 hex>`), as
+ * opposed to a person's name. Only agent-looking assignees can be orphaned.
+ *
+ * @param name - Assignee
+ * @returns True for a session-shaped name
+ */
+export function looksLikeAgentSession(name) {
+    return /^[a-z0-9][a-z0-9-]*-[0-9a-f]{8}$/.test(name);
+}
+/**
+ * Whether a ticket's assignee or team no longer exists.
+ *
+ * @param t - Ticket
+ * @param teams - All teams
+ * @returns The missing parts, or null when both (that are set) exist
+ */
+export function orphanReason(t, teams) {
+    const live = teams.filter((x) => !x.archived);
+    const reason = {};
+    if (t.team && !live.some((x) => x.id === t.team))
+        reason.team = t.team;
+    if (t.assignee && t.assignee !== ORCHESTRATOR_SESSION_NAME && looksLikeAgentSession(t.assignee)) {
+        const known = live.some((x) => (x.members ?? []).some((m) => m.sessionName === t.assignee || m.agentId === t.assignee));
+        if (!known)
+            reason.assignee = t.assignee;
+    }
+    return reason.assignee || reason.team ? reason : null;
+}
+/** Key of a ticket in the "already sent" memory. */
+export function ticketKey(projectPath, id) {
+    return `${projectPath}#${id}`;
+}
+/**
+ * The session that decides a team's stale tickets: its first lead that has a
+ * session, else the orchestrator.
+ *
+ * @param team - Team (null = no team)
+ * @returns Session and whether it is the fallback
+ */
+export function reviewTargetOf(team) {
+    if (team) {
+        const lead = getTeamLeads(team).find((m) => !!(m.sessionName || m.agentId));
+        if (lead)
+            return { target: (lead.sessionName || lead.agentId), fallback: false };
+    }
+    return { target: ORCHESTRATOR_SESSION_NAME, fallback: true };
+}
+/**
+ * Group the stale tickets by owning team, drop the ones sent within the
+ * cooldown, and cap each batch. A team with nothing stale has no batch.
+ *
+ * A ticket belongs to its `team`, else to the team its assignee is on, else to
+ * the only team working on its project, else to the orchestrator.
+ *
+ * @param input - Tickets, teams, clock, memory
+ * @returns One batch per team that has something to decide
+ */
+export function selectReviewBatches(input) {
+    const live = input.teams.filter((t) => !t.archived);
+    const byId = new Map(live.map((t) => [t.id, t]));
+    const teamOfSession = new Map();
+    for (const t of live)
+        for (const m of t.members ?? [])
+            for (const s of [m.sessionName, m.agentId])
+                if (s && !teamOfSession.has(s))
+                    teamOfSession.set(s, t);
+    const cooldownMs = C.REVIEW_COOLDOWN_DAYS * DAY_MS;
+    const groups = new Map();
+    for (const ticket of input.tickets) {
+        if (!OPEN_TICKET_STATUSES.has(ticket.status))
+            continue;
+        const staleness = ticketStaleness(ticket, input.nowMs);
+        const orphan = input.orphans?.get(ticketKey(ticket.projectPath, ticket.id));
+        const reasons = [];
+        if (staleness.stale)
+            reasons.push('stale');
+        if (orphan)
+            reasons.push('orphaned');
+        if (reasons.length === 0)
+            continue;
+        const sent = input.sentAt[ticketKey(ticket.projectPath, ticket.id)];
+        if (sent !== undefined && input.nowMs - sent < cooldownMs)
+            continue;
+        const projectTeams = live.filter((t) => (t.projectIds ?? []).includes(ticket.projectId));
+        const team = (ticket.team && byId.get(ticket.team)) ||
+            (ticket.assignee ? teamOfSession.get(ticket.assignee) : undefined) ||
+            // A project with exactly one team: that team owns its unowned tickets.
+            (projectTeams.length === 1 ? projectTeams[0] : undefined) ||
+            null;
+        if (team && input.skipTeamIds?.has(team.id))
+            continue;
+        const key = team ? team.id : 'orchestrator';
+        const g = groups.get(key) ?? { team, list: [] };
+        g.list.push({ ticket, staleness, reasons });
+        groups.set(key, g);
+    }
+    const batches = [];
+    for (const [key, g] of groups) {
+        const sorted = g.list.sort((a, b) => b.staleness.idleDays - a.staleness.idleDays || a.ticket.projectPath.localeCompare(b.ticket.projectPath) || a.ticket.id.localeCompare(b.ticket.id, undefined, { numeric: true }));
+        const { target, fallback } = reviewTargetOf(g.team);
+        batches.push({
+            key,
+            teamId: g.team?.id ?? null,
+            teamName: g.team?.name ?? 'No team',
+            target,
+            fallbackToOrchestrator: fallback,
+            candidates: sorted.slice(0, C.MAX_TICKETS_PER_REVIEW),
+            more: Math.max(0, sorted.length - C.MAX_TICKETS_PER_REVIEW),
+        });
+    }
+    return batches.sort((a, b) => a.key.localeCompare(b.key));
+}
+/**
+ * The brief the lead receives (WorkItem `briefMarkdown`): the list, the four
+ * ways to decide, and the rule that nothing here goes to the owner.
+ *
+ * @param batch - The batch
+ * @returns Markdown
+ */
+export function buildReviewBrief(batch) {
+    const tk = '$AGENT_SKILLS_PATH/core/project-tickets/execute.sh';
+    const n = batch.candidates.length;
+    const lines = [
+        `# Ticket review — ${batch.teamName} (${n} ticket${n === 1 ? '' : 's'})`,
+        '',
+        'These tickets have had no activity for a while, so status views (Drive mode, boards) may show them wrongly.',
+        `Decide every ticket below, then complete this WorkItem (complete-task with its id) with one line per ticket saying what you did. This is internal housekeeping: do not message the owner about it.`,
+        '',
+        '## For each ticket, do one of these',
+        '',
+        `1. **Finished** — a ticket in progress or in review: \`bash ${tk} update --project <PROJECT> --id <ID> --status done --note "<what shipped / where>"\`. A backlog or ready ticket cannot go straight to done: cancel it with the note "already done: <evidence>".`,
+        `2. **No longer wanted** — \`bash ${tk} update --project <PROJECT> --id <ID> --status cancelled --note "<why>"\`.`,
+        `3. **Still valid** — leave it and say so: \`bash ${tk} log --project <PROJECT> --id <ID> --note "still valid: <one line — status / next step / blocker>"\`. A ticket not worth doing soon: \`… update --project <PROJECT> --id <ID> --defer-until YYYY-MM-DD\`.`,
+        `4. **Status is wrong** — move it (\`… update --project <PROJECT> --id <ID> --status ready|review|…\`) or reassign it (\`… assign --project <PROJECT> --id <ID> --to <member>\`) with a one-line note. A ticket marked orphaned lost its assignee or team: give it a new owner or cancel it.`,
+        '',
+        'Look at the ticket (`… show --project <PROJECT> --id <ID>`) and its linked work before deciding; do not close work you cannot confirm. Any of these actions counts as the review, so a reviewed ticket is not listed again for a few days.',
+        '',
+        '## Tickets',
+        '',
+    ];
+    for (const c of batch.candidates) {
+        const t = c.ticket;
+        const last = c.staleness.lastActivityAt.slice(0, 10);
+        const bits = [
+            `**${t.id}**`,
+            `[${t.status}]`,
+            clip(t.title, C.TITLE_MAX_CHARS),
+            `project \`${t.projectId}\` (${t.projectName})`,
+            `no activity for ${c.staleness.idleDays} day${c.staleness.idleDays === 1 ? '' : 's'} (last ${last})`,
+            t.assignee ? `assignee ${t.assignee}` : 'unassigned',
+        ];
+        if (c.reasons.includes('orphaned'))
+            bits.push('ORPHANED (assignee or team no longer exists)');
+        lines.push(`- ${bits.join(' · ')}`);
+    }
+    if (batch.more > 0)
+        lines.push('', `${batch.more} more stale ticket${batch.more === 1 ? '' : 's'} will be listed in a later review.`);
+    lines.push('', `List all tickets of a project: \`bash ${tk} list --project <PROJECT>\`.`);
+    return lines.join('\n');
+}
+/**
+ * Cut a one-line string.
+ *
+ * @param text - Text
+ * @param max - Max characters
+ * @returns Text on one line, within `max`
+ */
+function clip(text, max) {
+    const one = String(text ?? '').replace(/\s+/g, ' ').trim();
+    return one.length <= max ? one : `${one.slice(0, max - 1)}…`;
+}
+//# sourceMappingURL=ticket-hygiene.js.map

package/dist/backend/backend/src/services/project-tickets/ticket-hygiene.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticket-hygiene.js","sourceRoot":"","sources":["../../../../../../backend/src/services/project-tickets/ticket-hygiene.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/project-tickets/ticket-hygiene.service.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Ticket hygiene service — keeps project tickets honest.
+ *
+ * Two jobs, both cheap:
+ *
+ * 1. **Auto-reconcile (no agent).** Each sweep closes or advances tickets
+ *    whose state is objectively settled (the linked WorkItem is verified /
+ *    done) and flags tickets whose assignee or team no longer exists. Every
+ *    change is logged and written to the ticket's Log with the reason
+ *    `auto-reconcile`.
+ * 2. **Stale review (one lead, once a day).** Open tickets with no activity
+ *    past a threshold are batched into ONE WorkItem per team for the team lead
+ *    (the orchestrator when the team has none) to close, cancel or annotate.
+ *
+ * Loop safety: at most one live review item per team, at most one batch per
+ * team per day, a ticket is not re-sent within the cooldown, and the sweep's
+ * own Log lines never count as ticket activity. Nothing here messages the owner.
+ *
+ * @module services/project-tickets/ticket-hygiene.service
+ */
+import { type ComponentLogger } from '../core/logger.service.js';
+import { type WorkItem } from '../../types/v2/work-item.types.js';
+import type { ProjectTicketService } from './project-ticket.service.js';
+import { type ChainEnd, type ProjectTicketDirectory } from './project-ticket-workflow.service.js';
+/** The pool operations the service uses. */
+export interface TicketHygienePool {
+    getAllItems(): Promise<WorkItem[]>;
+    addToPool(workItem: WorkItem): Promise<void>;
+    cancelQueued(workItemId: string, reason: string): Promise<void>;
+}
+/** Dependencies (injectable for tests). */
+export interface TicketHygieneDeps {
+    tickets: Pick<ProjectTicketService, 'list' | 'mutate'>;
+    pool: TicketHygienePool;
+    directory: ProjectTicketDirectory;
+    /** Follow a WorkItem to where its work stands (the workflow service's) */
+    followChain: (workItemId: string) => Promise<ChainEnd>;
+    /** Where the bookkeeping lives */
+    stateFile: string;
+    logger?: ComponentLogger;
+    now?: () => Date;
+}
+/** One automatic change, as logged. */
+export interface HygieneChange {
+    projectId: string;
+    ticketId: string;
+    kind: 'closed' | 'advanced' | 'flagged' | 'unflagged';
+    message: string;
+}
+/** What a run did. */
+export interface HygieneRunResult {
+    changes: HygieneChange[];
+    /** Review items created (one per team) */
+    reviewItems: Array<{
+        teamKey: string;
+        target: string;
+        workItemId: string;
+        tickets: number;
+    }>;
+}
+export declare class TicketHygieneService {
+    private readonly deps;
+    private static instance;
+    private readonly logger;
+    private state;
+    private timer;
+    private firstTimer;
+    private running;
+    /**
+     * @param deps - Ticket store, pool, directory, chain follower, state file
+     */
+    constructor(deps: TicketHygieneDeps);
+    /** @returns The wired instance, or null */
+    static getInstance(): TicketHygieneService | null;
+    /** @param service - Instance to install (null clears) */
+    static setInstance(service: TicketHygieneService | null): void;
+    /**
+     * Start the periodic sweep: a first run a few minutes after boot, then every
+     * {@link TICKET_HYGIENE_CONSTANTS.SWEEP_INTERVAL_MS}.
+     *
+     * @param intervalMs - Sweep interval (0 disables the timers)
+     * @param firstDelayMs - Delay of the first run
+     */
+    start(intervalMs?: number, firstDelayMs?: number): void;
+    /** Stop the timers. */
+    stop(): void;
+    /**
+     * One sweep: reconcile settled / orphaned tickets, then queue today's lead
+     * reviews. Safe to call at any time (a run already in progress is skipped).
+     *
+     * @returns What changed and which review items went out
+     */
+    runOnce(): Promise<HygieneRunResult>;
+    /**
+     * Close or advance an `in_progress` / `review` ticket whose linked work is
+     * all verified / done, honouring the done gate: a ticket with `ownerReview`
+     * lands in `review` (and stays there, waiting for the owner) instead of `done`.
+     *
+     * Only these two statuses are touched, so a person's move of a ticket back to
+     * `ready` / `backlog` is never fought.
+     *
+     * @param projectId - Project id (for the log)
+     * @param ticket - The ticket
+     * @param poolItems - Pool snapshot
+     * @returns The change, or null when nothing is settled
+     */
+    private reconcileSettled;
+    /**
+     * Keep the `orphaned` label in step with whether the assignee / team still
+     * exist. Bookkeeping only: `updatedAt` is left alone so a flag never makes a
+     * stale ticket look fresh.
+     *
+     * @param projectId - Project id (for the log)
+     * @param ticket - The ticket
+     * @param orphan - Missing parts, or null
+     * @returns The change, or null when the label already matches
+     */
+    private reconcileOrphanFlag;
+    /**
+     * Send today's batches: one WorkItem per team that has stale tickets, no
+     * more than one per team per day, none while a previous one is still live.
+     *
+     * @param tickets - Open tickets after reconcile
+     * @param teams - All teams
+     * @param orphans - Orphaned tickets
+     * @param nowMs - Clock
+     * @returns The items created
+     */
+    private queueReviews;
+    private now;
+    private pruneSent;
+    private loadState;
+    private saveState;
+}
+//# sourceMappingURL=ticket-hygiene.service.d.ts.map

package/dist/backend/backend/src/services/project-tickets/ticket-hygiene.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticket-hygiene.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/project-tickets/ticket-hygiene.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAEhF,OAAO,EAA4C,KAAK,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAI5G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAiB,KAAK,QAAQ,EAAE,KAAK,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAcjH,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,WAAW,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACnC,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAED,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;IACvD,IAAI,EAAE,iBAAiB,CAAC;IACxB,SAAS,EAAE,sBAAsB,CAAC;IAClC,0EAA0E;IAC1E,WAAW,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvD,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAUD,uCAAuC;AACvC,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sBAAsB;AACtB,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,0CAA0C;IAC1C,WAAW,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9F;AAED,qBAAa,oBAAoB;IAYnB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAXjC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAqC;IAE5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,OAAO,CAAS;IAExB;;OAEG;gBAC0B,IAAI,EAAE,iBAAiB;IAIpD,2CAA2C;IAC3C,MAAM,CAAC,WAAW,IAAI,oBAAoB,GAAG,IAAI;IAIjD,yDAAyD;IACzD,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI;IAI9D;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,GAAE,MAA4B,EAAE,YAAY,GAAE,MAA+B,GAAG,IAAI;IAcpG,uBAAuB;IACvB,IAAI,IAAI,IAAI;IAOZ;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC;IA4D1C;;;;;;;;;;;;OAYG;YACW,gBAAgB;IAiC9B;;;;;;;;;OASG;YACW,mBAAmB;IAwBjC;;;;;;;;;OASG;YACW,YAAY;IA6E1B,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,SAAS;YAKH,SAAS;YAUT,SAAS;CAQxB"}