sequant 1.13.5 → 1.14.1

package/dist/src/lib/scope/formatter.js

@@ -0,0 +1,169 @@
+/**
+ * Scope Assessment Formatter
+ *
+ * Formats scope assessment results as markdown for /spec output
+ * and GitHub issue comments.
+ *
+ * @example
+ * ```typescript
+ * import { formatScopeAssessment } from './formatter';
+ *
+ * const assessment = performScopeAssessment(criteria, issueBody, title);
+ * console.log(formatScopeAssessment(assessment));
+ * ```
+ */
+import { getVerdictEmoji, getStatusEmoji } from "./verdict.js";
+/**
+ * Format non-goals section for output
+ *
+ * @param nonGoals - Non-goals parsing result
+ * @returns Formatted markdown string
+ */
+export function formatNonGoals(nonGoals) {
+    const lines = ["### Non-Goals (Required)", ""];
+    if (!nonGoals.found) {
+        lines.push("⚠️ **Non-Goals section not found.** Consider adding scope boundaries.");
+        lines.push("");
+        lines.push("Example format:");
+        lines.push("```markdown");
+        lines.push("## Non-Goals");
+        lines.push("");
+        lines.push("What this issue explicitly will NOT do:");
+        lines.push("- [ ] [Adjacent feature we're deferring]");
+        lines.push("- [ ] [Scope boundary we're respecting]");
+        lines.push("- [ ] [Future work that's out of scope]");
+        lines.push("```");
+        return lines.join("\n");
+    }
+    if (nonGoals.items.length === 0) {
+        lines.push("⚠️ **Non-Goals section is empty.** Add explicit scope boundaries.");
+        return lines.join("\n");
+    }
+    lines.push(`✅ ${nonGoals.items.length} non-goal(s) defined:`);
+    lines.push("");
+    for (const item of nonGoals.items) {
+        lines.push(`- ${item}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Format scope metrics table
+ *
+ * @param assessment - Complete scope assessment
+ * @returns Formatted markdown table
+ */
+export function formatMetricsTable(assessment) {
+    const lines = [
+        "### Scope Metrics",
+        "",
+        "| Metric | Value | Status |",
+        "|--------|-------|--------|",
+    ];
+    for (const metric of assessment.metrics) {
+        const emoji = getStatusEmoji(metric.status);
+        lines.push(`| ${metric.name} | ${metric.value} | ${emoji} |`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Format scope verdict section
+ *
+ * @param assessment - Complete scope assessment
+ * @returns Formatted markdown string
+ */
+export function formatVerdict(assessment) {
+    const emoji = getVerdictEmoji(assessment.verdict);
+    const lines = [
+        "### Scope Verdict",
+        "",
+        `${emoji} **${assessment.verdict}** - ${assessment.recommendation}`,
+    ];
+    // Add split recommendation details if needed
+    if (assessment.verdict === "SCOPE_SPLIT_RECOMMENDED") {
+        lines.push("");
+        lines.push("**Suggested splits:**");
+        // Group ACs by cluster for split suggestions
+        const significantClusters = assessment.featureDetection.clusters.filter((c) => c.count >= 2);
+        if (significantClusters.length > 1) {
+            for (const cluster of significantClusters) {
+                lines.push(`- Issue for **${cluster.keyword}**: ${cluster.acIds.join(", ")}`);
+            }
+        }
+        else {
+            lines.push("- Consider separating by functional area");
+            lines.push("- Each issue should have a single deployable outcome");
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Format complete scope assessment section
+ *
+ * @param assessment - Complete scope assessment
+ * @returns Formatted markdown string
+ */
+export function formatScopeAssessment(assessment) {
+    if (assessment.skipped) {
+        return [
+            "## Scope Assessment",
+            "",
+            `*Skipped: ${assessment.skipReason}*`,
+        ].join("\n");
+    }
+    const sections = [
+        "## Scope Assessment",
+        "",
+        formatNonGoals(assessment.nonGoals),
+        "",
+        formatMetricsTable(assessment),
+        "",
+        formatVerdict(assessment),
+    ];
+    // Add quality loop recommendation if needed
+    if (assessment.verdict === "SCOPE_WARNING" ||
+        assessment.verdict === "SCOPE_SPLIT_RECOMMENDED") {
+        sections.push("");
+        sections.push("---");
+        sections.push("");
+        sections.push("**Quality Loop:** Will be auto-enabled due to scope concerns.");
+    }
+    return sections.join("\n");
+}
+/**
+ * Format condensed scope assessment for issue comments
+ *
+ * A shorter version suitable for GitHub issue comments.
+ *
+ * @param assessment - Complete scope assessment
+ * @returns Condensed markdown string
+ */
+export function formatCondensedAssessment(assessment) {
+    if (assessment.skipped) {
+        return `**Scope Assessment:** Skipped (${assessment.skipReason})`;
+    }
+    const emoji = getVerdictEmoji(assessment.verdict);
+    const lines = [
+        `### Scope Assessment: ${emoji} ${assessment.verdict}`,
+    ];
+    // Metrics in single line
+    const metricsLine = assessment.metrics
+        .map((m) => `${m.name}: ${m.value} ${getStatusEmoji(m.status)}`)
+        .join(" | ");
+    lines.push("");
+    lines.push(metricsLine);
+    // Non-goals summary
+    if (!assessment.nonGoals.found || assessment.nonGoals.items.length === 0) {
+        lines.push("");
+        lines.push("⚠️ Non-Goals: Not defined");
+    }
+    else {
+        lines.push("");
+        lines.push(`✅ Non-Goals: ${assessment.nonGoals.items.length} defined`);
+    }
+    // Recommendation if not OK
+    if (assessment.verdict !== "SCOPE_OK") {
+        lines.push("");
+        lines.push(`*${assessment.recommendation}*`);
+    }
+    return lines.join("\n");
+}

package/dist/src/lib/scope/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Scope Assessment Module
+ *
+ * Provides scope analysis for /spec to catch overscoped issues early.
+ *
+ * @example
+ * ```typescript
+ * import { performScopeAssessment, formatScopeAssessment } from './scope';
+ *
+ * const criteria = parseAcceptanceCriteria(issueBody);
+ * const assessment = performScopeAssessment(criteria, issueBody, issueTitle);
+ *
+ * if (assessment.verdict !== 'SCOPE_OK') {
+ *   console.log(formatScopeAssessment(assessment));
+ * }
+ * ```
+ */
+import type { AcceptanceCriterion } from "../workflow/state-schema.js";
+import type { ScopeAssessment, ScopeAssessmentConfig } from "./types.js";
+export type { ScopeVerdict, ScopeMetricStatus, ScopeMetric, ScopeAssessment, ScopeAssessmentConfig, MetricThreshold, ACCluster, FeatureDetection, NonGoals, } from "./types.js";
+export { DEFAULT_SCOPE_CONFIG, ScopeAssessmentSchema } from "./types.js";
+export { clusterACByKeyword, detectTitleVerbs, estimateDirectorySpread, calculateFeatureCount, detectFeatures, parseNonGoals, shouldSkipAssessment, } from "./analyzer.js";
+export { getMetricStatus, createScopeMetrics, calculateVerdict, generateRecommendation, getVerdictEmoji, getStatusEmoji, shouldEnableQualityLoop, } from "./verdict.js";
+export { formatNonGoals, formatMetricsTable, formatVerdict, formatScopeAssessment, formatCondensedAssessment, } from "./formatter.js";
+/**
+ * Perform complete scope assessment
+ *
+ * This is the main entry point for scope assessment.
+ *
+ * @param criteria - Parsed acceptance criteria
+ * @param issueBody - Full issue body markdown
+ * @param title - Issue title
+ * @param config - Optional custom configuration
+ * @returns Complete scope assessment result
+ */
+export declare function performScopeAssessment(criteria: AcceptanceCriterion[], issueBody: string, title: string, config?: ScopeAssessmentConfig): ScopeAssessment;

package/dist/src/lib/scope/index.js

@@ -0,0 +1,73 @@
+/**
+ * Scope Assessment Module
+ *
+ * Provides scope analysis for /spec to catch overscoped issues early.
+ *
+ * @example
+ * ```typescript
+ * import { performScopeAssessment, formatScopeAssessment } from './scope';
+ *
+ * const criteria = parseAcceptanceCriteria(issueBody);
+ * const assessment = performScopeAssessment(criteria, issueBody, issueTitle);
+ *
+ * if (assessment.verdict !== 'SCOPE_OK') {
+ *   console.log(formatScopeAssessment(assessment));
+ * }
+ * ```
+ */
+import { DEFAULT_SCOPE_CONFIG } from "./types.js";
+import { detectFeatures, parseNonGoals, shouldSkipAssessment, } from "./analyzer.js";
+import { createScopeMetrics, calculateVerdict, generateRecommendation, } from "./verdict.js";
+export { DEFAULT_SCOPE_CONFIG, ScopeAssessmentSchema } from "./types.js";
+// Re-export analyzer functions
+export { clusterACByKeyword, detectTitleVerbs, estimateDirectorySpread, calculateFeatureCount, detectFeatures, parseNonGoals, shouldSkipAssessment, } from "./analyzer.js";
+// Re-export verdict functions
+export { getMetricStatus, createScopeMetrics, calculateVerdict, generateRecommendation, getVerdictEmoji, getStatusEmoji, shouldEnableQualityLoop, } from "./verdict.js";
+// Re-export formatter functions
+export { formatNonGoals, formatMetricsTable, formatVerdict, formatScopeAssessment, formatCondensedAssessment, } from "./formatter.js";
+/**
+ * Perform complete scope assessment
+ *
+ * This is the main entry point for scope assessment.
+ *
+ * @param criteria - Parsed acceptance criteria
+ * @param issueBody - Full issue body markdown
+ * @param title - Issue title
+ * @param config - Optional custom configuration
+ * @returns Complete scope assessment result
+ */
+export function performScopeAssessment(criteria, issueBody, title, config = DEFAULT_SCOPE_CONFIG) {
+    // Parse non-goals first
+    const nonGoals = parseNonGoals(issueBody);
+    // Detect features
+    const featureDetection = detectFeatures(criteria, title);
+    // Check if we should skip (trivial issue)
+    const skipResult = shouldSkipAssessment(criteria.length, featureDetection.directorySpread, config);
+    if (skipResult.skip) {
+        return {
+            assessedAt: new Date().toISOString(),
+            skipped: true,
+            skipReason: skipResult.reason,
+            verdict: "SCOPE_OK",
+            metrics: [],
+            featureDetection,
+            nonGoals,
+            recommendation: "Trivial issue - scope assessment skipped.",
+        };
+    }
+    // Calculate metrics
+    const metrics = createScopeMetrics(featureDetection, criteria.length, config);
+    // Determine verdict
+    const verdict = calculateVerdict(metrics, nonGoals);
+    // Generate recommendation
+    const recommendation = generateRecommendation(verdict, metrics, featureDetection, nonGoals);
+    return {
+        assessedAt: new Date().toISOString(),
+        skipped: false,
+        verdict,
+        metrics,
+        featureDetection,
+        nonGoals,
+        recommendation,
+    };
+}

package/dist/src/lib/scope/types.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Scope Assessment Types
+ *
+ * Types for the scope assessment system that evaluates issue scope
+ * during the /spec phase to catch overscoped issues early.
+ */
+import { z } from "zod";
+/**
+ * Scope verdict - overall assessment result
+ */
+export type ScopeVerdict = "SCOPE_OK" | "SCOPE_WARNING" | "SCOPE_SPLIT_RECOMMENDED";
+/**
+ * Scope metric status based on thresholds
+ */
+export type ScopeMetricStatus = "green" | "yellow" | "red";
+/**
+ * Threshold configuration for a single metric
+ */
+export interface MetricThreshold {
+    /** Value at which status becomes yellow */
+    yellow: number;
+    /** Value at which status becomes red */
+    red: number;
+}
+/**
+ * Scope assessment configuration
+ */
+export interface ScopeAssessmentConfig {
+    /** Whether scope assessment is enabled */
+    enabled: boolean;
+    /** Skip assessment for trivial issues */
+    skipIfSimple: boolean;
+    /** Trivial issue thresholds (skip if below all) */
+    trivialThresholds: {
+        /** Maximum AC items for trivial classification */
+        maxACItems: number;
+        /** Maximum directories touched for trivial classification */
+        maxDirectories: number;
+    };
+    /** Thresholds for scope metrics */
+    thresholds: {
+        /** Feature count thresholds */
+        featureCount: MetricThreshold;
+        /** AC items thresholds */
+        acItems: MetricThreshold;
+        /** File estimate thresholds */
+        fileEstimate: MetricThreshold;
+        /** Directory spread thresholds */
+        directorySpread: MetricThreshold;
+    };
+}
+/**
+ * Default scope assessment configuration
+ */
+export declare const DEFAULT_SCOPE_CONFIG: ScopeAssessmentConfig;
+/**
+ * Individual scope metric
+ */
+export interface ScopeMetric {
+    /** Name of the metric */
+    name: string;
+    /** Current value */
+    value: number;
+    /** Status based on thresholds */
+    status: ScopeMetricStatus;
+}
+/**
+ * Clustering result for AC items
+ */
+export interface ACCluster {
+    /** Cluster identifier (keyword-based) */
+    keyword: string;
+    /** AC IDs in this cluster */
+    acIds: string[];
+    /** Number of AC items in cluster */
+    count: number;
+}
+/**
+ * Feature detection result
+ */
+export interface FeatureDetection {
+    /** Number of distinct features detected */
+    featureCount: number;
+    /** AC clusters by functional area */
+    clusters: ACCluster[];
+    /** Multiple verbs detected in title */
+    multipleVerbs: boolean;
+    /** Detected verb list from title */
+    titleVerbs: string[];
+    /** Directory spread detected */
+    directorySpread: number;
+    /** Detected directories from analysis */
+    directories: string[];
+}
+/**
+ * Non-goals section data
+ */
+export interface NonGoals {
+    /** List of non-goal items */
+    items: string[];
+    /** Whether non-goals section was found */
+    found: boolean;
+    /** Warning message if empty or missing */
+    warning?: string;
+}
+/**
+ * Complete scope assessment result
+ */
+export interface ScopeAssessment {
+    /** Timestamp of assessment */
+    assessedAt: string;
+    /** Whether assessment was skipped (trivial issue) */
+    skipped: boolean;
+    /** Reason for skipping (if skipped) */
+    skipReason?: string;
+    /** Overall verdict */
+    verdict: ScopeVerdict;
+    /** Individual metrics */
+    metrics: ScopeMetric[];
+    /** Feature detection details */
+    featureDetection: FeatureDetection;
+    /** Non-goals section */
+    nonGoals: NonGoals;
+    /** Recommendation message */
+    recommendation: string;
+}
+/**
+ * Zod schema for scope assessment (for state storage)
+ */
+export declare const ScopeMetricSchema: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodNumber;
+    status: z.ZodEnum<{
+        red: "red";
+        green: "green";
+        yellow: "yellow";
+    }>;
+}, z.core.$strip>;
+export declare const ACClusterSchema: z.ZodObject<{
+    keyword: z.ZodString;
+    acIds: z.ZodArray<z.ZodString>;
+    count: z.ZodNumber;
+}, z.core.$strip>;
+export declare const FeatureDetectionSchema: z.ZodObject<{
+    featureCount: z.ZodNumber;
+    clusters: z.ZodArray<z.ZodObject<{
+        keyword: z.ZodString;
+        acIds: z.ZodArray<z.ZodString>;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+    multipleVerbs: z.ZodBoolean;
+    titleVerbs: z.ZodArray<z.ZodString>;
+    directorySpread: z.ZodNumber;
+    directories: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const NonGoalsSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodString>;
+    found: z.ZodBoolean;
+    warning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ScopeAssessmentSchema: z.ZodObject<{
+    assessedAt: z.ZodString;
+    skipped: z.ZodBoolean;
+    skipReason: z.ZodOptional<z.ZodString>;
+    verdict: z.ZodEnum<{
+        SCOPE_OK: "SCOPE_OK";
+        SCOPE_WARNING: "SCOPE_WARNING";
+        SCOPE_SPLIT_RECOMMENDED: "SCOPE_SPLIT_RECOMMENDED";
+    }>;
+    metrics: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodNumber;
+        status: z.ZodEnum<{
+            red: "red";
+            green: "green";
+            yellow: "yellow";
+        }>;
+    }, z.core.$strip>>;
+    featureDetection: z.ZodObject<{
+        featureCount: z.ZodNumber;
+        clusters: z.ZodArray<z.ZodObject<{
+            keyword: z.ZodString;
+            acIds: z.ZodArray<z.ZodString>;
+            count: z.ZodNumber;
+        }, z.core.$strip>>;
+        multipleVerbs: z.ZodBoolean;
+        titleVerbs: z.ZodArray<z.ZodString>;
+        directorySpread: z.ZodNumber;
+        directories: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    nonGoals: z.ZodObject<{
+        items: z.ZodArray<z.ZodString>;
+        found: z.ZodBoolean;
+        warning: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    recommendation: z.ZodString;
+}, z.core.$strip>;
+export type ScopeMetricType = z.infer<typeof ScopeMetricSchema>;

package/dist/src/lib/scope/types.js

@@ -0,0 +1,60 @@
+/**
+ * Scope Assessment Types
+ *
+ * Types for the scope assessment system that evaluates issue scope
+ * during the /spec phase to catch overscoped issues early.
+ */
+import { z } from "zod";
+/**
+ * Default scope assessment configuration
+ */
+export const DEFAULT_SCOPE_CONFIG = {
+    enabled: true,
+    skipIfSimple: true,
+    trivialThresholds: {
+        maxACItems: 3,
+        maxDirectories: 1,
+    },
+    thresholds: {
+        featureCount: { yellow: 2, red: 3 },
+        acItems: { yellow: 6, red: 9 },
+        fileEstimate: { yellow: 8, red: 13 },
+        directorySpread: { yellow: 3, red: 5 },
+    },
+};
+/**
+ * Zod schema for scope assessment (for state storage)
+ */
+export const ScopeMetricSchema = z.object({
+    name: z.string(),
+    value: z.number(),
+    status: z.enum(["green", "yellow", "red"]),
+});
+export const ACClusterSchema = z.object({
+    keyword: z.string(),
+    acIds: z.array(z.string()),
+    count: z.number(),
+});
+export const FeatureDetectionSchema = z.object({
+    featureCount: z.number(),
+    clusters: z.array(ACClusterSchema),
+    multipleVerbs: z.boolean(),
+    titleVerbs: z.array(z.string()),
+    directorySpread: z.number(),
+    directories: z.array(z.string()),
+});
+export const NonGoalsSchema = z.object({
+    items: z.array(z.string()),
+    found: z.boolean(),
+    warning: z.string().optional(),
+});
+export const ScopeAssessmentSchema = z.object({
+    assessedAt: z.string().datetime(),
+    skipped: z.boolean(),
+    skipReason: z.string().optional(),
+    verdict: z.enum(["SCOPE_OK", "SCOPE_WARNING", "SCOPE_SPLIT_RECOMMENDED"]),
+    metrics: z.array(ScopeMetricSchema),
+    featureDetection: FeatureDetectionSchema,
+    nonGoals: NonGoalsSchema,
+    recommendation: z.string(),
+});

package/dist/src/lib/scope/verdict.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Scope Verdict Calculator
+ *
+ * Determines scope verdict based on metrics and thresholds.
+ * Provides recommendations for scope improvement.
+ *
+ * @example
+ * ```typescript
+ * import { calculateVerdict, getMetricStatus } from './verdict';
+ *
+ * const metrics = [
+ *   { name: 'featureCount', value: 2, status: 'yellow' },
+ *   { name: 'acItems', value: 8, status: 'yellow' },
+ * ];
+ * const verdict = calculateVerdict(metrics);
+ * // Returns: 'SCOPE_WARNING'
+ * ```
+ */
+import type { ScopeMetric, ScopeMetricStatus, ScopeVerdict, ScopeAssessmentConfig, MetricThreshold, FeatureDetection, NonGoals } from "./types.js";
+/**
+ * Get status for a metric value based on thresholds
+ *
+ * @param value - Current metric value
+ * @param threshold - Threshold configuration
+ * @returns Metric status (green/yellow/red)
+ */
+export declare function getMetricStatus(value: number, threshold: MetricThreshold): ScopeMetricStatus;
+/**
+ * Create scope metrics from feature detection result
+ *
+ * @param detection - Feature detection result
+ * @param acCount - Total AC items count
+ * @param config - Scope assessment configuration
+ * @returns Array of scope metrics with status
+ */
+export declare function createScopeMetrics(detection: FeatureDetection, acCount: number, config?: ScopeAssessmentConfig): ScopeMetric[];
+/**
+ * Calculate overall verdict from metrics
+ *
+ * Logic:
+ * - Any red metric → SCOPE_SPLIT_RECOMMENDED
+ * - Any yellow metric → SCOPE_WARNING
+ * - All green → SCOPE_OK
+ *
+ * @param metrics - Array of scope metrics
+ * @param nonGoals - Non-goals parsing result
+ * @returns Overall scope verdict
+ */
+export declare function calculateVerdict(metrics: ScopeMetric[], nonGoals: NonGoals): ScopeVerdict;
+/**
+ * Generate recommendation message based on verdict and metrics
+ *
+ * @param verdict - Calculated verdict
+ * @param metrics - Scope metrics
+ * @param detection - Feature detection result
+ * @param nonGoals - Non-goals parsing result
+ * @returns Recommendation message
+ */
+export declare function generateRecommendation(verdict: ScopeVerdict, metrics: ScopeMetric[], detection: FeatureDetection, nonGoals: NonGoals): string;
+/**
+ * Get emoji indicator for verdict
+ *
+ * @param verdict - Scope verdict
+ * @returns Emoji string
+ */
+export declare function getVerdictEmoji(verdict: ScopeVerdict): string;
+/**
+ * Get emoji indicator for metric status
+ *
+ * @param status - Metric status
+ * @returns Emoji string
+ */
+export declare function getStatusEmoji(status: ScopeMetricStatus): string;
+/**
+ * Check if quality loop should be auto-enabled based on verdict
+ *
+ * @param verdict - Scope verdict
+ * @returns Whether to enable quality loop
+ */
+export declare function shouldEnableQualityLoop(verdict: ScopeVerdict): boolean;