@backburner/cli 0.1.0

package/dist/src/retrospectives/scopes.js

@@ -0,0 +1,272 @@
+import * as path from "node:path";
+export function normalizeRetrospectiveScopes(input) {
+    const { rawSuggestedScopes, affectedRepoIds, roles, taskKinds, providers } = input;
+    const semanticScopes = [];
+    const candidateLearningScopes = [];
+    const seenKeys = new Set();
+    const addCandidate = (scope) => {
+        const key = JSON.stringify(scope);
+        if (!seenKeys.has(key)) {
+            seenKeys.add(key);
+            candidateLearningScopes.push(scope);
+        }
+    };
+    const semanticKinds = [
+        "workflow",
+        "configuration",
+        "guidance",
+        "orchestration",
+    ];
+    for (const raw of rawSuggestedScopes) {
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            addCandidate(raw);
+            continue;
+        }
+        const obj = raw;
+        const kind = obj.kind;
+        if (typeof kind !== "string") {
+            continue;
+        }
+        // Is it already a valid learning scope kind?
+        if (SCOPE_PRECEDENCE_ORDER.includes(kind)) {
+            addCandidate(raw);
+            continue;
+        }
+        // Is it a known semantic kind?
+        if (semanticKinds.includes(kind)) {
+            const semanticKind = kind;
+            semanticScopes.push({
+                kind: semanticKind,
+                raw,
+                reason: typeof obj.reason === "string" ? obj.reason : undefined,
+            });
+            // Expand candidates
+            switch (semanticKind) {
+                case "workflow":
+                    for (const repoId of affectedRepoIds) {
+                        for (const taskKind of taskKinds) {
+                            addCandidate({ kind: "repo_task_kind", repoId, taskKind });
+                        }
+                    }
+                    for (const taskKind of taskKinds) {
+                        addCandidate({ kind: "task_kind", taskKind });
+                    }
+                    for (const repoId of affectedRepoIds) {
+                        addCandidate({ kind: "repo", repoId });
+                    }
+                    addCandidate({ kind: "global" });
+                    break;
+                case "configuration":
+                    for (const repoId of affectedRepoIds) {
+                        for (const provider of providers) {
+                            addCandidate({ kind: "repo_provider", repoId, provider });
+                        }
+                    }
+                    for (const provider of providers) {
+                        addCandidate({ kind: "provider", provider });
+                    }
+                    for (const repoId of affectedRepoIds) {
+                        addCandidate({ kind: "repo", repoId });
+                    }
+                    addCandidate({ kind: "global" });
+                    break;
+                case "guidance":
+                    for (const repoId of affectedRepoIds) {
+                        for (const role of roles) {
+                            addCandidate({ kind: "repo_role", repoId, role });
+                        }
+                    }
+                    for (const repoId of affectedRepoIds) {
+                        for (const taskKind of taskKinds) {
+                            addCandidate({ kind: "repo_task_kind", repoId, taskKind });
+                        }
+                    }
+                    for (const role of roles) {
+                        addCandidate({ kind: "role", role });
+                    }
+                    for (const taskKind of taskKinds) {
+                        addCandidate({ kind: "task_kind", taskKind });
+                    }
+                    addCandidate({ kind: "global" });
+                    break;
+                case "orchestration":
+                    for (const repoId of affectedRepoIds) {
+                        for (const taskKind of taskKinds) {
+                            addCandidate({ kind: "repo_task_kind", repoId, taskKind });
+                        }
+                    }
+                    for (const repoId of affectedRepoIds) {
+                        for (const role of roles) {
+                            addCandidate({ kind: "repo_role", repoId, role });
+                        }
+                    }
+                    for (const repoId of affectedRepoIds) {
+                        addCandidate({ kind: "repo", repoId });
+                    }
+                    addCandidate({ kind: "global" });
+                    break;
+            }
+        }
+        else {
+            // Not a known semantic kind, pass it through as a candidate so validation can report it
+            addCandidate(raw);
+        }
+    }
+    return {
+        semanticScopes,
+        candidateLearningScopes,
+    };
+}
+export const SCOPE_PRECEDENCE_ORDER = [
+    "repo_task_kind",
+    "repo_role",
+    "repo_provider",
+    "repo",
+    "task_kind",
+    "role",
+    "provider",
+    "global",
+];
+export function validateLearningScope(input, config) {
+    // Guard: must be a plain non-null object
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return { ok: false, error: "Scope input must be a plain object" };
+    }
+    const obj = input;
+    // Guard: kind must be present and must be a known ScopeKind string
+    const { kind, ...rest } = obj;
+    if (typeof kind !== "string") {
+        return { ok: false, error: "Scope input must have a string \"kind\" field" };
+    }
+    if (!SCOPE_PRECEDENCE_ORDER.includes(kind)) {
+        return { ok: false, error: `Unknown scope kind: "${kind}"` };
+    }
+    // Dispatch to per-kind validation
+    switch (kind) {
+        case "global": {
+            if (Object.keys(rest).length > 0) {
+                return { ok: false, error: `Scope "global" must have no keys besides "kind", got extra: ${Object.keys(rest).join(", ")}` };
+            }
+            return { ok: true, scope: { kind: "global" } };
+        }
+        case "provider": {
+            const { provider, ...extra } = rest;
+            if (Object.keys(extra).length > 0) {
+                return { ok: false, error: `Scope "provider" has extra keys: ${Object.keys(extra).join(", ")}` };
+            }
+            if (typeof provider !== "string" || !config.providers.includes(provider)) {
+                return { ok: false, error: `Unknown provider: "${provider}"` };
+            }
+            return { ok: true, scope: { kind: "provider", provider: provider } };
+        }
+        case "role": {
+            const { role, ...extra } = rest;
+            if (Object.keys(extra).length > 0) {
+                return { ok: false, error: `Scope "role" has extra keys: ${Object.keys(extra).join(", ")}` };
+            }
+            if (typeof role !== "string" || !config.roles.includes(role)) {
+                return { ok: false, error: `Unknown role: "${role}"` };
+            }
+            return { ok: true, scope: { kind: "role", role: role } };
+        }
+        case "task_kind": {
+            const { taskKind, ...extra } = rest;
+            if (Object.keys(extra).length > 0) {
+                return { ok: false, error: `Scope "task_kind" has extra keys: ${Object.keys(extra).join(", ")}` };
+            }
+            if (typeof taskKind !== "string" || !config.taskKinds.includes(taskKind)) {
+                return { ok: false, error: `Unknown task kind: "${taskKind}"` };
+            }
+            return { ok: true, scope: { kind: "task_kind", taskKind: taskKind } };
+        }
+        case "repo": {
+            const { repoId, ...extra } = rest;
+            if (Object.keys(extra).length > 0) {
+                return { ok: false, error: `Scope "repo" has extra keys: ${Object.keys(extra).join(", ")}` };
+            }
+            if (typeof repoId !== "string" || !config.repoIds.includes(repoId)) {
+                return { ok: false, error: `Unknown repo ID: "${repoId}"` };
+            }
+            return { ok: true, scope: { kind: "repo", repoId } };
+        }
+        case "repo_provider": {
+            const { repoId, provider, ...extra } = rest;
+            if (Object.keys(extra).length > 0) {
+                return { ok: false, error: `Scope "repo_provider" has extra keys: ${Object.keys(extra).join(", ")}` };
+            }
+            if (typeof repoId !== "string" || !config.repoIds.includes(repoId)) {
+                return { ok: false, error: `Unknown repo ID: "${repoId}"` };
+            }
+            if (typeof provider !== "string" || !config.providers.includes(provider)) {
+                return { ok: false, error: `Unknown provider: "${provider}"` };
+            }
+            return { ok: true, scope: { kind: "repo_provider", repoId, provider: provider } };
+        }
+        case "repo_role": {
+            const { repoId, role, ...extra } = rest;
+            if (Object.keys(extra).length > 0) {
+                return { ok: false, error: `Scope "repo_role" has extra keys: ${Object.keys(extra).join(", ")}` };
+            }
+            if (typeof repoId !== "string" || !config.repoIds.includes(repoId)) {
+                return { ok: false, error: `Unknown repo ID: "${repoId}"` };
+            }
+            if (typeof role !== "string" || !config.roles.includes(role)) {
+                return { ok: false, error: `Unknown role: "${role}"` };
+            }
+            return { ok: true, scope: { kind: "repo_role", repoId, role: role } };
+        }
+        case "repo_task_kind": {
+            const { repoId, taskKind, ...extra } = rest;
+            if (Object.keys(extra).length > 0) {
+                return { ok: false, error: `Scope "repo_task_kind" has extra keys: ${Object.keys(extra).join(", ")}` };
+            }
+            if (typeof repoId !== "string" || !config.repoIds.includes(repoId)) {
+                return { ok: false, error: `Unknown repo ID: "${repoId}"` };
+            }
+            if (typeof taskKind !== "string" || !config.taskKinds.includes(taskKind)) {
+                return { ok: false, error: `Unknown task kind: "${taskKind}"` };
+            }
+            return { ok: true, scope: { kind: "repo_task_kind", repoId, taskKind: taskKind } };
+        }
+        default: {
+            const exhaustiveCheck = kind;
+            return { ok: false, error: `Unhandled scope kind: "${exhaustiveCheck}"` };
+        }
+    }
+}
+export function resolveScopePath(scope, managementRoot) {
+    const learningsRoot = path.resolve(managementRoot, "learnings");
+    let relative;
+    switch (scope.kind) {
+        case "global":
+            relative = "global.md";
+            break;
+        case "provider":
+            relative = path.join("providers", `${scope.provider}.md`);
+            break;
+        case "role":
+            relative = path.join("roles", `${scope.role}.md`);
+            break;
+        case "task_kind":
+            relative = path.join("task-kinds", `${scope.taskKind}.md`);
+            break;
+        case "repo":
+            relative = path.join("repos", `${scope.repoId}.md`);
+            break;
+        case "repo_provider":
+            relative = path.join("repo-providers", scope.repoId, `${scope.provider}.md`);
+            break;
+        case "repo_role":
+            relative = path.join("repo-roles", scope.repoId, `${scope.role}.md`);
+            break;
+        case "repo_task_kind":
+            relative = path.join("repo-task-kinds", scope.repoId, `${scope.taskKind}.md`);
+            break;
+    }
+    const resolved = path.resolve(learningsRoot, relative);
+    // Guard: resolved path must stay under learningsRoot
+    if (!resolved.startsWith(learningsRoot + path.sep) && resolved !== learningsRoot) {
+        throw new Error(`Path traversal detected: scope resolved to "${resolved}" which escapes learnings root "${learningsRoot}"`);
+    }
+    return resolved;
+}

package/dist/src/retrospectives/scoring.js

@@ -0,0 +1,171 @@
+import { validateLearningScope, normalizeRetrospectiveScopes, SCOPE_PRECEDENCE_ORDER, } from "./scopes.js";
+import { workflowRegistry } from "../workflows/registry.js";
+export function scoreRetrospectiveProblem(input) {
+    const { problem, scopeValidationConfig, now } = input;
+    const criteria = [];
+    const reasons = [];
+    // 1. Impact must be high
+    const impactPassed = problem.impact === "high";
+    const impactCriterion = {
+        criterion: "impact",
+        passed: impactPassed,
+        actual: problem.impact,
+        expected: "high",
+        reason: impactPassed ? "impact is high" : `impact is ${problem.impact || "missing"}; expected "high"`,
+    };
+    criteria.push(impactCriterion);
+    if (!impactPassed)
+        reasons.push(impactCriterion.reason);
+    // 2. Transferability must be high
+    const transferabilityPassed = problem.transferability === "high";
+    const transferabilityCriterion = {
+        criterion: "transferability",
+        passed: transferabilityPassed,
+        actual: problem.transferability,
+        expected: "high",
+        reason: transferabilityPassed ? "transferability is high" : `transferability is ${problem.transferability || "missing"}; expected "high"`,
+    };
+    criteria.push(transferabilityCriterion);
+    if (!transferabilityPassed)
+        reasons.push(transferabilityCriterion.reason);
+    // 3. Confidence must be high
+    const confidencePassed = problem.confidence === "high";
+    const confidenceCriterion = {
+        criterion: "confidence",
+        passed: confidencePassed,
+        actual: problem.confidence,
+        expected: "high",
+        reason: confidencePassed ? "confidence is high" : `confidence is ${problem.confidence || "missing"}; expected "high"`,
+    };
+    criteria.push(confidenceCriterion);
+    if (!confidencePassed)
+        reasons.push(confidenceCriterion.reason);
+    // 4. Improvement Likelihood must be high
+    const improvementLikelihoodPassed = problem.improvementLikelihood === "high";
+    const improvementLikelihoodCriterion = {
+        criterion: "improvementLikelihood",
+        passed: improvementLikelihoodPassed,
+        actual: problem.improvementLikelihood,
+        expected: "high",
+        reason: improvementLikelihoodPassed ? "improvementLikelihood is high" : `improvementLikelihood is ${problem.improvementLikelihood || "missing"}; expected "high"`,
+    };
+    criteria.push(improvementLikelihoodCriterion);
+    if (!improvementLikelihoodPassed)
+        reasons.push(improvementLikelihoodCriterion.reason);
+    // 5. Overfitting Risk must be low
+    const overfittingRiskPassed = problem.overfittingRisk === "low";
+    const overfittingRiskCriterion = {
+        criterion: "overfittingRisk",
+        passed: overfittingRiskPassed,
+        actual: problem.overfittingRisk,
+        expected: "low",
+        reason: overfittingRiskPassed ? "overfittingRisk is low" : `overfittingRisk is ${problem.overfittingRisk || "missing"}; expected "low"`,
+    };
+    criteria.push(overfittingRiskCriterion);
+    if (!overfittingRiskPassed)
+        reasons.push(overfittingRiskCriterion.reason);
+    // 6. Scope validation
+    let selectedScope;
+    let scopeValidationReason;
+    const validScopes = [];
+    const invalidScopeReasons = [];
+    // Defensive normalization for older persisted state or direct callers
+    const { semanticScopes, candidateLearningScopes } = normalizeRetrospectiveScopes({
+        rawSuggestedScopes: problem.suggestedScopes,
+        affectedRepoIds: problem.affectedRepoIds,
+        roles: problem.roles,
+        taskKinds: problem.taskKinds,
+        providers: problem.providers,
+    });
+    const normalizedSuggestedScopes = candidateLearningScopes;
+    const normalizedAnySemantic = semanticScopes.length > 0 || (problem.semanticSuggestedScopes?.length ?? 0) > 0;
+    for (const suggested of normalizedSuggestedScopes) {
+        const validation = validateLearningScope(suggested, scopeValidationConfig);
+        if (validation.ok) {
+            validScopes.push(validation.scope);
+        }
+        else {
+            invalidScopeReasons.push(validation.error);
+        }
+    }
+    if (validScopes.length > 0) {
+        // Select the narrowest scope by SCOPE_PRECEDENCE_ORDER
+        validScopes.sort((a, b) => {
+            const aIdx = SCOPE_PRECEDENCE_ORDER.indexOf(a.kind);
+            const bIdx = SCOPE_PRECEDENCE_ORDER.indexOf(b.kind);
+            return aIdx - bIdx;
+        });
+        selectedScope = validScopes[0];
+        if (selectedScope) {
+            scopeValidationReason = `selected scope ${selectedScope.kind} validated${normalizedAnySemantic ? " after normalizing semantic scopes" : ""}`;
+        }
+        else {
+            // Should not happen given validScopes.length > 0
+            scopeValidationReason = "no valid scopes found after validation";
+        }
+    }
+    else {
+        scopeValidationReason = invalidScopeReasons.length > 0
+            ? `no suggested scope validated successfully: ${invalidScopeReasons.join("; ")}`
+            : "no suggested scopes provided";
+    }
+    const scopePassed = !!selectedScope;
+    const scopeCriterion = {
+        criterion: "scope",
+        passed: scopePassed,
+        expected: "at least one valid scope",
+        reason: scopeValidationReason,
+    };
+    criteria.push(scopeCriterion);
+    if (!scopePassed)
+        reasons.push(scopeValidationReason);
+    const allPassed = criteria.every((c) => c.passed);
+    const decision = allPassed ? "pass" : "fail";
+    return {
+        problem: {
+            ...problem,
+            suggestedScopes: normalizedSuggestedScopes,
+            rawSuggestedScopes: problem.rawSuggestedScopes || problem.suggestedScopes,
+            semanticSuggestedScopes: problem.semanticSuggestedScopes || (semanticScopes.length > 0 ? semanticScopes : undefined),
+            thresholdDecision: decision,
+            thresholdCriteria: criteria,
+            thresholdReasons: reasons,
+            selectedScope,
+            scopeValidationReason,
+            decisionReason: allPassed ? "All criteria passed" : reasons.join("; "),
+            updatedAt: now,
+        },
+    };
+}
+export function scoreRetrospectiveProblems(problems, scopeValidationConfig, now) {
+    return problems.map((p) => {
+        // Only rescore if needed (no decision yet, or newly ingested)
+        // For now, let's implement the idempotent rescoring as requested.
+        const result = scoreRetrospectiveProblem({ problem: p, scopeValidationConfig, now });
+        // To avoid needlessly changing updatedAt on already-scored unchanged problems,
+        // we can compare the result.
+        if (p.thresholdDecision === result.problem.thresholdDecision &&
+            p.decisionReason === result.problem.decisionReason &&
+            JSON.stringify(p.thresholdCriteria) === JSON.stringify(result.problem.thresholdCriteria) &&
+            JSON.stringify(p.selectedScope) === JSON.stringify(result.problem.selectedScope) &&
+            JSON.stringify(p.suggestedScopes) === JSON.stringify(result.problem.suggestedScopes) &&
+            JSON.stringify(p.rawSuggestedScopes) === JSON.stringify(result.problem.rawSuggestedScopes) &&
+            JSON.stringify(p.semanticSuggestedScopes) === JSON.stringify(result.problem.semanticSuggestedScopes)) {
+            return p;
+        }
+        return result.problem;
+    });
+}
+export function buildScopeValidationConfigFromRuntime(input) {
+    const { repos, agents } = input;
+    const repoIds = repos.filter((r) => r.enabled).map((r) => r.id);
+    const providers = agents.filter((a) => a.enabled).map((a) => a.provider);
+    const roles = Array.from(new Set(agents.filter((a) => a.enabled).flatMap((a) => a.roles)));
+    const taskKinds = workflowRegistry.definitionsList.map((def) => def.kind);
+    return {
+        repoIds,
+        providers,
+        roles,
+        taskKinds,
+    };
+}

package/dist/src/retrospectives/types.js

@@ -0,0 +1 @@
+export {};