@aquex/cmos-mcp 1.0.0

package/dist/tools/cmos/staleness-detection.js

@@ -0,0 +1,381 @@
+"use strict";
+/**
+ * Staleness Detection
+ *
+ * Detects and flags decisions/learnings that are older than N sprints
+ * and haven't been referenced. Surfaces stale counts for agent awareness.
+ *
+ * Staleness is sprint-based: items linked to sprints older than the threshold
+ * (default 20) relative to the current sprint are candidates. Items that are
+ * referenced (via supersession chains or evidence links) are exempt.
+ *
+ * @module tools/cmos/staleness-detection
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STALENESS_THRESHOLD = void 0;
+exports.detectAndFlagStaleness = detectAndFlagStaleness;
+exports.getStaleCounts = getStaleCounts;
+exports.reviewDecisionStaleness = reviewDecisionStaleness;
+const schema_migrations_1 = require("./schema-migrations");
+/**
+ * Default staleness threshold in sprints.
+ *
+ * Sprint 61 m02 — raised from 10 → 20. Halves trigger frequency without losing
+ * the abandonment signal: a learning that hasn't been touched OR cited across
+ * 20 sprints is genuinely stale, not just dormant. The original 10-sprint
+ * threshold was tripping the same institutional rules every sprint and
+ * compounding the staleness pile faster than it could be triaged.
+ *
+ * Override at runtime via `CMOS_STALENESS_THRESHOLD_SPRINTS`. Tests should
+ * import this constant rather than hard-coding 20 so future bumps don't
+ * require test churn.
+ */
+exports.DEFAULT_STALENESS_THRESHOLD = 20;
+const STALENESS_THRESHOLD_ENV = 'CMOS_STALENESS_THRESHOLD_SPRINTS';
+/**
+ * Detect and flag stale decisions and learnings.
+ *
+ * Idempotent: re-running produces the same result. Items already flagged as
+ * 'stale' are not re-flagged. Items with status other than 'active' are skipped.
+ *
+ * Referenced items are exempt:
+ * - Decisions that are the target of another decision's superseded_by
+ * - Decisions with non-null evidence links
+ *
+ * @param client - Database client
+ * @param options - Optional threshold override
+ * @returns Staleness detection result with counts
+ */
+function detectAndFlagStaleness(client, options) {
+    const threshold = resolveThreshold(options?.threshold);
+    // Sprint 52 m03: ensure last_reviewed_at exists before the staleness query reads it.
+    // Sprint 61 m03: ensure the learnings.evergreen column exists on the read path so
+    // un-migrated DBs self-heal before the WHERE evergreen = 0 filter is evaluated.
+    // Both calls are idempotent and cheap once the columns are in place.
+    (0, schema_migrations_1.ensureReviewTimestamps)(client);
+    (0, schema_migrations_1.ensureLearningsTable)(client);
+    // Get the current sprint number
+    const currentSprintNumber = getCurrentSprintNumber(client);
+    if (currentSprintNumber === null) {
+        // No sprints — nothing to flag
+        return {
+            decisionsFlagged: 0,
+            learningsFlagged: 0,
+            totalStaleDecisions: countStale(client, 'strategic_decisions'),
+            totalStaleLearnings: countStale(client, 'learnings'),
+            threshold,
+            currentSprintNumber: null,
+            cutoffSprintNumber: null,
+        };
+    }
+    const cutoffSprintNumber = currentSprintNumber - threshold;
+    if (cutoffSprintNumber < 1) {
+        // Not enough sprints to trigger staleness
+        return {
+            decisionsFlagged: 0,
+            learningsFlagged: 0,
+            totalStaleDecisions: countStale(client, 'strategic_decisions'),
+            totalStaleLearnings: countStale(client, 'learnings'),
+            threshold,
+            currentSprintNumber,
+            cutoffSprintNumber,
+        };
+    }
+    // Get sprint IDs that are at or below the cutoff
+    const staleSprintIds = getStaleSprintIds(client, cutoffSprintNumber);
+    if (staleSprintIds.length === 0) {
+        return {
+            decisionsFlagged: 0,
+            learningsFlagged: 0,
+            totalStaleDecisions: countStale(client, 'strategic_decisions'),
+            totalStaleLearnings: countStale(client, 'learnings'),
+            threshold,
+            currentSprintNumber,
+            cutoffSprintNumber,
+        };
+    }
+    const placeholders = staleSprintIds.map(() => '?').join(', ');
+    // Flag stale decisions (excluding referenced ones)
+    const decisionsFlagged = flagStaleDecisions(client, staleSprintIds, placeholders);
+    // Flag stale learnings
+    const learningsFlagged = flagStaleLearnings(client, staleSprintIds, placeholders);
+    return {
+        decisionsFlagged,
+        learningsFlagged,
+        totalStaleDecisions: countStale(client, 'strategic_decisions'),
+        totalStaleLearnings: countStale(client, 'learnings'),
+        threshold,
+        currentSprintNumber,
+        cutoffSprintNumber,
+    };
+}
+/**
+ * Get stale counts without flagging (read-only).
+ * Useful when you want to report counts without mutating.
+ *
+ * Sprint 61 m03: ensures the learnings.evergreen column exists before reading
+ * (the count filters on `evergreen = 0` to exclude institutional rules).
+ */
+function getStaleCounts(client) {
+    (0, schema_migrations_1.ensureLearningsTable)(client);
+    return {
+        staleDecisions: countStale(client, 'strategic_decisions'),
+        staleLearnings: countStale(client, 'learnings'),
+    };
+}
+/**
+ * Get detailed staleness review for all decisions needing attention.
+ * Returns per-decision scoring and suggested actions.
+ *
+ * Unlike detectAndFlagStaleness, this does NOT mutate the database.
+ * It provides a read-only view for agents to triage.
+ */
+function reviewDecisionStaleness(client, options) {
+    const threshold = resolveThreshold(options?.threshold);
+    const includeApproaching = options?.includeApproaching ?? true;
+    const currentSprintNumber = getCurrentSprintNumber(client);
+    const totalActive = countByStatus(client, 'strategic_decisions', 'active');
+    const totalStale = countStale(client, 'strategic_decisions');
+    if (currentSprintNumber === null) {
+        return { decisions: [], totalActive, totalStale, currentSprintNumber: null, threshold };
+    }
+    // Get referenced decision IDs (supersession targets)
+    const referencedIds = getReferencedDecisionIds(client);
+    // Load candidates: stale + active decisions with sprint IDs
+    const statusFilter = includeApproaching ? `status IN ('stale', 'active')` : `status = 'stale'`;
+    const result = client.getMany(`SELECT id, decision_text, status, sprint_id, category, evidence
+     FROM strategic_decisions
+     WHERE ${statusFilter} AND sprint_id IS NOT NULL
+     ORDER BY sprint_id ASC, id ASC`, []);
+    if (!result.success || !result.data) {
+        return { decisions: [], totalActive, totalStale, currentSprintNumber, threshold };
+    }
+    const decisions = [];
+    for (const row of result.data) {
+        const sprintNum = extractSprintNumber(row.sprint_id);
+        if (sprintNum === null)
+            continue;
+        const sprintAge = currentSprintNumber - sprintNum;
+        if (sprintAge < 1)
+            continue; // Skip current sprint decisions
+        // Only include decisions beyond half the threshold (approaching) or already stale
+        if (includeApproaching && sprintAge < Math.floor(threshold / 2) && row.status !== 'stale') {
+            continue;
+        }
+        const stalenessScore = Math.min(sprintAge / threshold, 1.0);
+        const hasEvidence = !!(row.evidence && row.evidence !== '[]' && row.evidence !== '');
+        const isReferenced = referencedIds.has(row.id);
+        // Determine suggested action
+        let suggestedAction;
+        let suggestedReason;
+        if (hasEvidence || isReferenced) {
+            suggestedAction = 'confirm';
+            suggestedReason = hasEvidence
+                ? 'Has evidence references — confirm still relevant or archive'
+                : 'Referenced by supersession chain — confirm still relevant';
+        }
+        else if (stalenessScore >= 0.8) {
+            suggestedAction = 'archive';
+            suggestedReason = `${sprintAge} sprints old — likely no longer actionable`;
+        }
+        else {
+            suggestedAction = 'review';
+            suggestedReason = `${sprintAge} sprints old — approaching staleness threshold (${threshold})`;
+        }
+        decisions.push({
+            id: row.id,
+            text: row.decision_text.length > 200
+                ? row.decision_text.slice(0, 197) + '...'
+                : row.decision_text,
+            status: row.status,
+            sprintId: row.sprint_id,
+            sprintAge,
+            stalenessScore: Math.round(stalenessScore * 100) / 100,
+            category: row.category,
+            hasEvidence,
+            isReferenced,
+            suggestedAction,
+            suggestedReason,
+        });
+    }
+    // Sort by staleness score descending (most stale first)
+    decisions.sort((a, b) => b.stalenessScore - a.stalenessScore);
+    return { decisions, totalActive, totalStale, currentSprintNumber, threshold };
+}
+/**
+ * Get IDs of decisions that are referenced by supersession chains.
+ */
+function getReferencedDecisionIds(client) {
+    const result = client.getMany(`SELECT DISTINCT superseded_by FROM strategic_decisions WHERE superseded_by IS NOT NULL`, []);
+    if (!result.success || !result.data)
+        return new Set();
+    return new Set(result.data.map((r) => r.superseded_by));
+}
+function countByStatus(client, tableName, status) {
+    const result = client.getOne(`SELECT COUNT(*) AS count FROM ${tableName} WHERE status = ?`, [status]);
+    return result.success ? (result.data?.count ?? 0) : 0;
+}
+function resolveThreshold(explicit) {
+    if (explicit !== undefined && explicit > 0) {
+        return explicit;
+    }
+    const envValue = process.env[STALENESS_THRESHOLD_ENV];
+    if (envValue) {
+        const parsed = Number.parseInt(envValue, 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return exports.DEFAULT_STALENESS_THRESHOLD;
+}
+/**
+ * Get the current (most recent active/planned) sprint number.
+ * Returns the highest sprint number from non-completed sprints,
+ * or the highest overall if all are completed.
+ */
+function getCurrentSprintNumber(client) {
+    // Try active sprint first
+    const activeResult = client.getOne(`SELECT id FROM sprints
+     WHERE status IN ('Active', 'In Progress', 'Current')
+     ORDER BY rowid DESC LIMIT 1`, []);
+    if (activeResult.success && activeResult.data) {
+        const num = extractSprintNumber(activeResult.data.id);
+        if (num !== null)
+            return num;
+    }
+    // Fallback to highest numbered sprint
+    const allResult = client.getMany('SELECT id FROM sprints ORDER BY rowid DESC', []);
+    if (allResult.success && allResult.data) {
+        for (const row of allResult.data) {
+            const num = extractSprintNumber(row.id);
+            if (num !== null)
+                return num;
+        }
+    }
+    return null;
+}
+/**
+ * Extract the numeric suffix from a sprint ID like "sprint-26" → 26.
+ */
+function extractSprintNumber(sprintId) {
+    const match = sprintId.match(/^sprint-(\d+)$/);
+    if (!match)
+        return null;
+    const num = Number.parseInt(match[1], 10);
+    return Number.isFinite(num) ? num : null;
+}
+/**
+ * Get sprint IDs whose numeric suffix is at or below the cutoff.
+ */
+function getStaleSprintIds(client, cutoffSprintNumber) {
+    const result = client.getMany('SELECT id FROM sprints', []);
+    if (!result.success || !result.data)
+        return [];
+    return result.data
+        .filter((row) => {
+        const num = extractSprintNumber(row.id);
+        return num !== null && num <= cutoffSprintNumber;
+    })
+        .map((row) => row.id);
+}
+/**
+ * Flag stale decisions. Excludes:
+ * - Decisions that are targets of supersession chains (another decision points to them)
+ * - Decisions with non-null evidence
+ */
+function flagStaleDecisions(client, staleSprintIds, placeholders) {
+    // Check if the table and required columns exist
+    const columns = getTableColumns(client, 'strategic_decisions');
+    if (!columns.has('status') || !columns.has('sprint_id'))
+        return 0;
+    const hasSupersededBy = columns.has('superseded_by');
+    const hasEvidence = columns.has('evidence');
+    const hasReviewTimestamp = columns.has('last_reviewed_at');
+    // Build exclusion clause for referenced decisions
+    const exclusions = [];
+    if (hasSupersededBy) {
+        exclusions.push(`id NOT IN (SELECT DISTINCT superseded_by FROM strategic_decisions WHERE superseded_by IS NOT NULL)`);
+    }
+    if (hasEvidence) {
+        exclusions.push(`(evidence IS NULL OR evidence = '[]' OR evidence = '')`);
+    }
+    const exclusionClause = exclusions.length > 0 ? `AND ${exclusions.join(' AND ')}` : '';
+    const reviewClause = hasReviewTimestamp
+        ? `AND (last_reviewed_at IS NULL OR last_reviewed_at < ?)`
+        : '';
+    const cutoffIso = computeReviewCutoffIso();
+    const params = [...staleSprintIds];
+    if (hasReviewTimestamp)
+        params.push(cutoffIso);
+    const result = client.execute(`UPDATE strategic_decisions SET status = 'stale'
+     WHERE status = 'active'
+       AND sprint_id IN (${placeholders})
+       ${reviewClause}
+       ${exclusionClause}`, params);
+    return result.success ? (result.data?.changes ?? 0) : 0;
+}
+/**
+ * Flag stale learnings.
+ *
+ * Sprint 52 m03: learnings whose last_reviewed_at (or, when null, created_at) is
+ * newer than the cutoff are exempt. This stops re-flagging learnings that an
+ * operator has already triaged — archive/supersede/reaffirm all bump the review
+ * timestamp, so the next staleness pass leaves them alone.
+ *
+ * Sprint 61 m03: learnings flagged `evergreen = 1` (institutional rules) drop
+ * out of staleness entirely. The column is added by `ensureLearningsTable` on
+ * the read path, so un-migrated DBs self-heal before this query runs.
+ */
+function flagStaleLearnings(client, staleSprintIds, placeholders) {
+    const columns = getTableColumns(client, 'learnings');
+    if (!columns.has('status') || !columns.has('sprint_id'))
+        return 0;
+    const hasReviewTimestamp = columns.has('last_reviewed_at');
+    const hasEvergreen = columns.has('evergreen');
+    // A learning with a recent last_reviewed_at has been triaged by an operator
+    // (status change or reaffirm) and must not be re-flagged by the sprint-age rule.
+    // When last_reviewed_at is NULL the sprint-id rule alone governs staleness (preserves
+    // historical behavior). The cutoff is ~threshold × 14 days back from now.
+    const reviewClause = hasReviewTimestamp
+        ? `AND (last_reviewed_at IS NULL OR last_reviewed_at < ?)`
+        : '';
+    const evergreenClause = hasEvergreen ? `AND evergreen = 0` : '';
+    const cutoffIso = computeReviewCutoffIso();
+    const params = [...staleSprintIds];
+    if (hasReviewTimestamp)
+        params.push(cutoffIso);
+    const result = client.execute(`UPDATE learnings SET status = 'stale'
+     WHERE status = 'active'
+       AND sprint_id IN (${placeholders})
+       ${reviewClause}
+       ${evergreenClause}`, params);
+    return result.success ? (result.data?.changes ?? 0) : 0;
+}
+/**
+ * Compute a review cutoff date: now - (DEFAULT_STALENESS_THRESHOLD * ~14 days/sprint).
+ * A learning whose last_reviewed_at is newer than this cutoff is considered "recently
+ * triaged" and exempt from re-flagging.
+ */
+function computeReviewCutoffIso() {
+    const msPerSprint = 14 * 24 * 60 * 60 * 1000;
+    return new Date(Date.now() - exports.DEFAULT_STALENESS_THRESHOLD * msPerSprint).toISOString();
+}
+function countStale(client, tableName) {
+    const columns = getTableColumns(client, tableName);
+    if (!columns.has('status'))
+        return 0;
+    // Sprint 61 m03: evergreen rows on the learnings table are excluded from the
+    // surfaced count so an institutional-rule learning that was flagged `stale`
+    // BEFORE evergreen was set drops out of the warning the moment the operator
+    // toggles the flag — without needing to reset its status.
+    const evergreenClause = columns.has('evergreen') ? ` AND evergreen = 0` : '';
+    const result = client.getOne(`SELECT COUNT(*) AS count FROM ${tableName} WHERE status = 'stale'${evergreenClause}`, []);
+    return result.success ? (result.data?.count ?? 0) : 0;
+}
+function getTableColumns(client, tableName) {
+    const result = client.getMany(`PRAGMA table_info('${tableName}')`, []);
+    if (!result.success || !result.data)
+        return new Set();
+    return new Set(result.data.map((row) => row.name));
+}
+//# sourceMappingURL=staleness-detection.js.map

package/dist/tools/cmos/staleness-detection.js.map

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

package/dist/tools/cmos/supersession-detection.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Supersession Detection
+ *
+ * When a new decision is captured, searches existing active decisions for
+ * keyword overlap using FTS5. Returns candidate decisions that the new one
+ * may supersede. No auto-supersession — returns suggestions only.
+ *
+ * @module tools/cmos/supersession-detection
+ */
+import type { CmosDatabaseClient } from './client';
+export interface SupersessionCandidate {
+    /** ID of the existing decision */
+    id: number;
+    /** Text of the existing decision */
+    decisionText: string;
+    /** Sprint the existing decision belongs to */
+    sprintId: string | null;
+    /** When the existing decision was created */
+    createdAt: string;
+    /** Number of overlapping keywords */
+    overlapCount: number;
+}
+export interface SupersessionSuggestion {
+    /** Candidates that may be superseded by the new decision */
+    candidates: SupersessionCandidate[];
+    /** Human-readable suggestion text */
+    message: string | null;
+}
+/**
+ * Detect potential supersession candidates for a newly captured decision.
+ *
+ * Extracts keywords from the new decision text, searches active decisions
+ * via FTS5 (with keyword fallback), and returns up to MAX_CANDIDATES matches.
+ *
+ * @param client - Database client
+ * @param newDecisionText - The newly captured decision text
+ * @param excludeDecisionId - ID of the new decision to exclude from results
+ * @returns Supersession suggestion with candidates
+ */
+export declare function detectSupersessionCandidates(client: CmosDatabaseClient, newDecisionText: string, excludeDecisionId?: number): SupersessionSuggestion;
+/**
+ * Extract meaningful keywords from decision text.
+ * Filters out stop words and short tokens.
+ */
+export declare function extractKeywords(text: string): string[];
+//# sourceMappingURL=supersession-detection.d.ts.map

package/dist/tools/cmos/supersession-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supersession-detection.d.ts","sourceRoot":"","sources":["../../../src/tools/cmos/supersession-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAOnD,MAAM,WAAW,qBAAqB;IACpC,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IAEX,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IAErB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAExB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAElB,qCAAqC;IACrC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,UAAU,EAAE,qBAAqB,EAAE,CAAC;IAEpC,qCAAqC;IACrC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,kBAAkB,EAC1B,eAAe,EAAE,MAAM,EACvB,iBAAiB,CAAC,EAAE,MAAM,GACzB,sBAAsB,CAsBxB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAStD"}