sequant 1.15.2 → 1.15.3

package/dist/src/lib/workflow/log-writer.d.ts

@@ -24,6 +24,8 @@ export interface LogWriterOptions {
     verbose?: boolean;
     /** Log rotation settings */
     rotation?: RotationSettings;
+    /** Git commit SHA at run start (AC-2) */
+    startCommit?: string;
 }
 /**
  * Manages writing structured run logs to disk
@@ -35,6 +37,7 @@ export declare class LogWriter {
     private writeToUserLogs;
     private verbose;
     private rotation;
+    private startCommit?;
     constructor(options?: LogWriterOptions);
     /**
      * Initialize a new run log
@@ -65,9 +68,13 @@ export declare class LogWriter {
      *
      * Automatically rotates old logs if thresholds are exceeded.
      *
+     * @param options - Optional finalization options
+     * @param options.endCommit - Git commit SHA at run end (AC-2)
      * @returns Path to the written log file
      */
-    finalize(): Promise<string>;
+    finalize(options?: {
+        endCommit?: string;
+    }): Promise<string>;
     /**
      * Get the current run log (for inspection)
      */
@@ -85,4 +92,4 @@ export declare class LogWriter {
  *
  * Utility function for creating phase logs when you have start/end times.
  */
-export declare function createPhaseLogFromTiming(phase: Phase, issueNumber: number, startTime: Date, endTime: Date, status: PhaseLog["status"], options?: Partial<Pick<PhaseLog, "error" | "iterations" | "filesModified" | "testsRun" | "testsPassed" | "verdict">>): PhaseLog;
+export declare function createPhaseLogFromTiming(phase: Phase, issueNumber: number, startTime: Date, endTime: Date, status: PhaseLog["status"], options?: Partial<Pick<PhaseLog, "error" | "iterations" | "filesModified" | "testsRun" | "testsPassed" | "verdict" | "commitHash" | "fileDiffStats" | "cacheMetrics">>): PhaseLog;

package/dist/src/lib/workflow/log-writer.js

@@ -28,11 +28,13 @@ export class LogWriter {
     writeToUserLogs;
     verbose;
     rotation;
+    startCommit;
     constructor(options = {}) {
         this.logPath = options.logPath ?? LOG_PATHS.project;
         this.writeToUserLogs = options.writeToUserLogs ?? false;
         this.verbose = options.verbose ?? false;
         this.rotation = options.rotation ?? DEFAULT_ROTATION_SETTINGS;
+        this.startCommit = options.startCommit;
     }
     /**
      * Initialize a new run log
@@ -40,7 +42,7 @@ export class LogWriter {
      * @param config - Run configuration
      */
     async initialize(config) {
-        this.runLog = createEmptyRunLog(config);
+        this.runLog = createEmptyRunLog(config, { startCommit: this.startCommit });
         // Ensure log directory exists
         await this.ensureLogDirectory(this.logPath);
         if (this.writeToUserLogs) {
@@ -124,9 +126,11 @@ export class LogWriter {
      *
      * Automatically rotates old logs if thresholds are exceeded.
      *
+     * @param options - Optional finalization options
+     * @param options.endCommit - Git commit SHA at run end (AC-2)
      * @returns Path to the written log file
      */
-    async finalize() {
+    async finalize(options) {
         if (!this.runLog) {
             throw new Error("LogWriter not initialized.");
         }
@@ -134,7 +138,9 @@ export class LogWriter {
         if (this.currentIssue) {
             this.completeIssue();
         }
-        const finalLog = finalizeRunLog(this.runLog);
+        const finalLog = finalizeRunLog(this.runLog, {
+            endCommit: options?.endCommit,
+        });
         const filename = generateLogFilename(finalLog.runId, new Date(finalLog.startTime));
         // Write to project logs
         const projectPath = path.join(this.resolvePath(this.logPath), filename);

package/dist/src/lib/workflow/metrics-schema.d.ts

@@ -48,6 +48,9 @@ export declare const RunMetricsSchema: z.ZodObject<{
     linesAdded: z.ZodNumber;
     acceptanceCriteria: z.ZodNumber;
     qaIterations: z.ZodNumber;
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    cacheTokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type RunMetrics = z.infer<typeof RunMetricsSchema>;
 /**
@@ -86,6 +89,9 @@ export declare const MetricRunSchema: z.ZodObject<{
         linesAdded: z.ZodNumber;
         acceptanceCriteria: z.ZodNumber;
         qaIterations: z.ZodNumber;
+        inputTokens: z.ZodOptional<z.ZodNumber>;
+        outputTokens: z.ZodOptional<z.ZodNumber>;
+        cacheTokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type MetricRun = z.infer<typeof MetricRunSchema>;
@@ -123,6 +129,9 @@ export declare const MetricsSchema: z.ZodObject<{
             linesAdded: z.ZodNumber;
             acceptanceCriteria: z.ZodNumber;
             qaIterations: z.ZodNumber;
+            inputTokens: z.ZodOptional<z.ZodNumber>;
+            outputTokens: z.ZodOptional<z.ZodNumber>;
+            cacheTokens: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>;
     }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/src/lib/workflow/metrics-schema.js

@@ -38,7 +38,7 @@ export const MetricPhaseSchema = z.enum([
  * Note: No file paths or code content - only aggregate counts
  */
 export const RunMetricsSchema = z.object({
-    /** Estimated tokens used (if available, 0 if not) */
+    /** Estimated tokens used (if available, 0 if not) - total of input + output */
     tokensUsed: z.number().int().nonnegative(),
     /** Number of files changed during the run */
     filesChanged: z.number().int().nonnegative(),
@@ -48,6 +48,12 @@ export const RunMetricsSchema = z.object({
     acceptanceCriteria: z.number().int().nonnegative(),
     /** Number of QA iterations needed */
     qaIterations: z.number().int().nonnegative(),
+    /** Input tokens used (AC-4 token breakdown) */
+    inputTokens: z.number().int().nonnegative().optional(),
+    /** Output tokens used (AC-4 token breakdown) */
+    outputTokens: z.number().int().nonnegative().optional(),
+    /** Cache tokens (creation + read) (AC-4 token breakdown) */
+    cacheTokens: z.number().int().nonnegative().optional(),
 });
 /**
  * Single workflow run record
@@ -121,6 +127,9 @@ export function createMetricRun(options) {
             linesAdded: options.metrics?.linesAdded ?? 0,
             acceptanceCriteria: options.metrics?.acceptanceCriteria ?? 0,
             qaIterations: options.metrics?.qaIterations ?? 0,
+            inputTokens: options.metrics?.inputTokens,
+            outputTokens: options.metrics?.outputTokens,
+            cacheTokens: options.metrics?.cacheTokens,
         },
     };
 }

package/dist/src/lib/workflow/phase-detection.d.ts

@@ -21,6 +21,9 @@ export declare function formatPhaseMarker(marker: PhaseMarker): string;
 /**
  * Parse all phase markers from a single comment body.
  *
+ * Phase markers inside fenced code blocks (```...```) or inline code (`...`)
+ * are ignored to prevent false positives from documentation examples.
+ *
  * @param commentBody - The full body text of a GitHub comment
  * @returns Array of parsed phase markers (empty if none found)
  */

package/dist/src/lib/workflow/phase-detection.js

@@ -14,6 +14,27 @@ import { execSync } from "child_process";
 import { PhaseMarkerSchema, WORKFLOW_PHASES, } from "./state-schema.js";
 /** Regex to extract phase marker JSON from HTML comments */
 const PHASE_MARKER_REGEX = /<!-- SEQUANT_PHASE: (\{[^}]+\}) -->/g;
+/**
+ * Regex patterns for markdown code constructs that should be ignored.
+ * - Fenced code blocks: 3+ backticks or tildes (CommonMark spec)
+ * - Inline code: `...`
+ */
+const FENCED_CODE_BLOCK_REGEX = /`{3,}[\s\S]*?`{3,}|~{3,}[\s\S]*?~{3,}/g;
+const INLINE_CODE_REGEX = /`[^`\n]+`/g;
+/**
+ * Strip markdown code blocks and inline code from text.
+ * This prevents phase markers inside code examples from being parsed.
+ *
+ * @param text - The text to strip code from
+ * @returns Text with code blocks and inline code removed
+ */
+function stripMarkdownCode(text) {
+    // First remove fenced code blocks (multi-line)
+    let result = text.replace(FENCED_CODE_BLOCK_REGEX, "");
+    // Then remove inline code
+    result = result.replace(INLINE_CODE_REGEX, "");
+    return result;
+}
 /**
  * Format a phase marker as an HTML comment string for embedding in GitHub comments.
  *
@@ -26,15 +47,20 @@ export function formatPhaseMarker(marker) {
 /**
  * Parse all phase markers from a single comment body.
  *
+ * Phase markers inside fenced code blocks (```...```) or inline code (`...`)
+ * are ignored to prevent false positives from documentation examples.
+ *
  * @param commentBody - The full body text of a GitHub comment
  * @returns Array of parsed phase markers (empty if none found)
  */
 export function parsePhaseMarkers(commentBody) {
     const markers = [];
+    // Strip code blocks before matching to avoid false positives
+    const strippedBody = stripMarkdownCode(commentBody);
     // Reset regex state for reuse
     PHASE_MARKER_REGEX.lastIndex = 0;
     let match;
-    while ((match = PHASE_MARKER_REGEX.exec(commentBody)) !== null) {
+    while ((match = PHASE_MARKER_REGEX.exec(strippedBody)) !== null) {
         try {
             const parsed = JSON.parse(match[1]);
             const result = PhaseMarkerSchema.safeParse(parsed);

package/dist/src/lib/workflow/qa-cache.d.ts

@@ -28,7 +28,7 @@ import { z } from "zod";
 /**
  * Check types that can be cached
  */
-export declare const CHECK_TYPES: readonly ["type-safety", "deleted-tests", "scope", "size", "security", "semgrep", "build", "tests"];
+export declare const CHECK_TYPES: readonly ["type-safety", "deleted-tests", "scope", "size", "security", "semgrep", "build", "tests", "test-quality"];
 export type CheckType = (typeof CHECK_TYPES)[number];
 /**
  * Schema for a single cached check result
@@ -43,6 +43,7 @@ export declare const CachedCheckResultSchema: z.ZodObject<{
         scope: "scope";
         size: "size";
         tests: "tests";
+        "test-quality": "test-quality";
     }>;
     diffHash: z.ZodString;
     configHash: z.ZodString;
@@ -71,6 +72,7 @@ export declare const QACacheSchema: z.ZodObject<{
             scope: "scope";
             size: "size";
             tests: "tests";
+            "test-quality": "test-quality";
         }>;
         diffHash: z.ZodString;
         configHash: z.ZodString;

package/dist/src/lib/workflow/qa-cache.js

@@ -41,6 +41,7 @@ export const CHECK_TYPES = [
     "semgrep",
     "build",
     "tests",
+    "test-quality",
 ];
 /**
  * Schema for a single cached check result
@@ -106,6 +107,7 @@ const CHECK_INVALIDATION_PATTERNS = {
     semgrep: [/\.ts$/, /\.tsx$/, /\.js$/, /\.jsx$/, /semgrep.*\.ya?ml$/],
     build: [/\.ts$/, /\.tsx$/, /\.js$/, /\.jsx$/, /tsconfig.*\.json$/],
     tests: [/\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /jest\.config/],
+    "test-quality": [/\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/],
 };
 /**
  * QA Cache Manager

package/dist/src/lib/workflow/run-log-schema.d.ts

@@ -58,6 +58,30 @@ export declare const QaVerdictSchema: z.ZodEnum<{
     NEEDS_VERIFICATION: "NEEDS_VERIFICATION";
 }>;
 export type QaVerdict = z.infer<typeof QaVerdictSchema>;
+/**
+ * File diff statistics for a single file (AC-3)
+ */
+export declare const FileDiffStatSchema: z.ZodObject<{
+    path: z.ZodString;
+    additions: z.ZodNumber;
+    deletions: z.ZodNumber;
+    status: z.ZodEnum<{
+        modified: "modified";
+        added: "added";
+        deleted: "deleted";
+        renamed: "renamed";
+    }>;
+}, z.core.$strip>;
+export type FileDiffStat = z.infer<typeof FileDiffStatSchema>;
+/**
+ * Cache metrics for QA phase (AC-7)
+ */
+export declare const CacheMetricsSchema: z.ZodObject<{
+    hits: z.ZodNumber;
+    misses: z.ZodNumber;
+    skipped: z.ZodNumber;
+}, z.core.$strip>;
+export type CacheMetrics = z.infer<typeof CacheMetricsSchema>;
 /**
  * Log entry for a single phase execution
  */
@@ -92,6 +116,23 @@ export declare const PhaseLogSchema: z.ZodObject<{
         AC_NOT_MET: "AC_NOT_MET";
         NEEDS_VERIFICATION: "NEEDS_VERIFICATION";
     }>>;
+    commitHash: z.ZodOptional<z.ZodString>;
+    fileDiffStats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        additions: z.ZodNumber;
+        deletions: z.ZodNumber;
+        status: z.ZodEnum<{
+            modified: "modified";
+            added: "added";
+            deleted: "deleted";
+            renamed: "renamed";
+        }>;
+    }, z.core.$strip>>>;
+    cacheMetrics: z.ZodOptional<z.ZodObject<{
+        hits: z.ZodNumber;
+        misses: z.ZodNumber;
+        skipped: z.ZodNumber;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PhaseLog = z.infer<typeof PhaseLogSchema>;
 /**
@@ -137,6 +178,23 @@ export declare const IssueLogSchema: z.ZodObject<{
             AC_NOT_MET: "AC_NOT_MET";
             NEEDS_VERIFICATION: "NEEDS_VERIFICATION";
         }>>;
+        commitHash: z.ZodOptional<z.ZodString>;
+        fileDiffStats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            additions: z.ZodNumber;
+            deletions: z.ZodNumber;
+            status: z.ZodEnum<{
+                modified: "modified";
+                added: "added";
+                deleted: "deleted";
+                renamed: "renamed";
+            }>;
+        }, z.core.$strip>>>;
+        cacheMetrics: z.ZodOptional<z.ZodObject<{
+            hits: z.ZodNumber;
+            misses: z.ZodNumber;
+            skipped: z.ZodNumber;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     totalDurationSeconds: z.ZodNumber;
 }, z.core.$strip>;
@@ -237,6 +295,23 @@ export declare const RunLogSchema: z.ZodObject<{
                 AC_NOT_MET: "AC_NOT_MET";
                 NEEDS_VERIFICATION: "NEEDS_VERIFICATION";
             }>>;
+            commitHash: z.ZodOptional<z.ZodString>;
+            fileDiffStats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                additions: z.ZodNumber;
+                deletions: z.ZodNumber;
+                status: z.ZodEnum<{
+                    modified: "modified";
+                    added: "added";
+                    deleted: "deleted";
+                    renamed: "renamed";
+                }>;
+            }, z.core.$strip>>>;
+            cacheMetrics: z.ZodOptional<z.ZodObject<{
+                hits: z.ZodNumber;
+                misses: z.ZodNumber;
+                skipped: z.ZodNumber;
+            }, z.core.$strip>>;
         }, z.core.$strip>>;
         totalDurationSeconds: z.ZodNumber;
     }, z.core.$strip>>;
@@ -246,6 +321,8 @@ export declare const RunLogSchema: z.ZodObject<{
         failed: z.ZodNumber;
         totalDurationSeconds: z.ZodNumber;
     }, z.core.$strip>;
+    startCommit: z.ZodOptional<z.ZodString>;
+    endCommit: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type RunLog = z.infer<typeof RunLogSchema>;
 /**
@@ -269,9 +346,12 @@ export declare function generateLogFilename(runId: string, startTime: Date): str
  * Create an empty run log with initial values
  *
  * @param config - Run configuration
+ * @param options - Optional fields including startCommit
  * @returns Initial RunLog structure
  */
-export declare function createEmptyRunLog(config: RunConfig): Omit<RunLog, "endTime">;
+export declare function createEmptyRunLog(config: RunConfig, options?: {
+    startCommit?: string;
+}): Omit<RunLog, "endTime">;
 /**
  * Create a phase log entry
  *
@@ -288,11 +368,14 @@ export declare function createPhaseLog(phase: Phase, issueNumber: number): Omit<
  * @param options - Additional fields (error, filesModified, verdict, etc.)
  * @returns Complete PhaseLog
  */
-export declare function completePhaseLog(phaseLog: Omit<PhaseLog, "endTime" | "durationSeconds" | "status">, status: PhaseStatus, options?: Partial<Pick<PhaseLog, "error" | "iterations" | "filesModified" | "testsRun" | "testsPassed" | "verdict">>): PhaseLog;
+export declare function completePhaseLog(phaseLog: Omit<PhaseLog, "endTime" | "durationSeconds" | "status">, status: PhaseStatus, options?: Partial<Pick<PhaseLog, "error" | "iterations" | "filesModified" | "testsRun" | "testsPassed" | "verdict" | "commitHash" | "fileDiffStats" | "cacheMetrics">>): PhaseLog;
 /**
  * Finalize a run log with summary statistics
  *
  * @param runLog - Partial run log
+ * @param options - Optional fields including endCommit
  * @returns Complete RunLog with endTime and summary
  */
-export declare function finalizeRunLog(runLog: Omit<RunLog, "endTime">): RunLog;
+export declare function finalizeRunLog(runLog: Omit<RunLog, "endTime">, options?: {
+    endCommit?: string;
+}): RunLog;

package/dist/src/lib/workflow/run-log-schema.js

@@ -51,6 +51,30 @@ export const QaVerdictSchema = z.enum([
     "AC_NOT_MET",
     "NEEDS_VERIFICATION",
 ]);
+/**
+ * File diff statistics for a single file (AC-3)
+ */
+export const FileDiffStatSchema = z.object({
+    /** File path relative to repository root */
+    path: z.string(),
+    /** Number of lines added */
+    additions: z.number().int().nonnegative(),
+    /** Number of lines deleted */
+    deletions: z.number().int().nonnegative(),
+    /** Change status */
+    status: z.enum(["added", "modified", "deleted", "renamed"]),
+});
+/**
+ * Cache metrics for QA phase (AC-7)
+ */
+export const CacheMetricsSchema = z.object({
+    /** Number of cache hits */
+    hits: z.number().int().nonnegative(),
+    /** Number of cache misses */
+    misses: z.number().int().nonnegative(),
+    /** Number of skipped checks */
+    skipped: z.number().int().nonnegative(),
+});
 /**
  * Log entry for a single phase execution
  */
@@ -79,6 +103,12 @@ export const PhaseLogSchema = z.object({
     testsPassed: z.number().int().nonnegative().optional(),
     /** Parsed QA verdict (only for qa phase) */
     verdict: QaVerdictSchema.optional(),
+    /** Git commit SHA after phase completes (AC-2) */
+    commitHash: z.string().optional(),
+    /** Per-file diff statistics (AC-3) */
+    fileDiffStats: z.array(FileDiffStatSchema).optional(),
+    /** Cache metrics for QA phase (AC-7) */
+    cacheMetrics: CacheMetricsSchema.optional(),
 });
 /**
  * Complete execution record for a single issue
@@ -147,6 +177,10 @@ export const RunLogSchema = z.object({
     issues: z.array(IssueLogSchema),
     /** Summary statistics */
     summary: RunSummarySchema,
+    /** Git commit SHA at run start (AC-2) */
+    startCommit: z.string().optional(),
+    /** Git commit SHA at run end (AC-2) */
+    endCommit: z.string().optional(),
 });
 /**
  * Default log directory paths
@@ -172,9 +206,10 @@ export function generateLogFilename(runId, startTime) {
  * Create an empty run log with initial values
  *
  * @param config - Run configuration
+ * @param options - Optional fields including startCommit
  * @returns Initial RunLog structure
  */
-export function createEmptyRunLog(config) {
+export function createEmptyRunLog(config, options) {
     const runId = randomUUID();
     const startTime = new Date().toISOString();
     return {
@@ -189,6 +224,7 @@ export function createEmptyRunLog(config) {
             failed: 0,
             totalDurationSeconds: 0,
         },
+        startCommit: options?.startCommit,
     };
 }
 /**
@@ -229,9 +265,10 @@ export function completePhaseLog(phaseLog, status, options) {
  * Finalize a run log with summary statistics
  *
  * @param runLog - Partial run log
+ * @param options - Optional fields including endCommit
  * @returns Complete RunLog with endTime and summary
  */
-export function finalizeRunLog(runLog) {
+export function finalizeRunLog(runLog, options) {
     const endTime = new Date();
     const startTime = new Date(runLog.startTime);
     const totalDurationSeconds = (endTime.getTime() - startTime.getTime()) / 1000;
@@ -246,5 +283,6 @@ export function finalizeRunLog(runLog) {
             failed,
             totalDurationSeconds,
         },
+        endCommit: options?.endCommit ?? runLog.endCommit,
     };
 }

package/dist/src/lib/workflow/state-utils.d.ts

@@ -128,3 +128,49 @@ export interface DiscoverResult {
  * and returns information about worktrees not yet in the state file.
  */
 export declare function discoverUntrackedWorktrees(options?: DiscoverOptions): Promise<DiscoverResult>;
+export interface ReconcileOptions {
+    /** State file path (default: .sequant/state.json) */
+    statePath?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+export interface ReconcileResult {
+    /** Whether reconciliation was successful */
+    success: boolean;
+    /** Issues that were advanced from ready_for_merge to merged */
+    advanced: number[];
+    /** Issues checked but still ready_for_merge */
+    stillPending: number[];
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Check if a branch has been merged into main using git
+ *
+ * @param branchName - The branch name to check (e.g., "feature/33-some-title")
+ * @returns true if the branch is merged into main, false otherwise
+ */
+export declare function isBranchMergedIntoMain(branchName: string): boolean;
+/**
+ * Check if a feature branch for an issue is merged into main
+ *
+ * Tries multiple detection methods:
+ * 1. Check if branch exists and is merged via `git branch --merged main`
+ * 2. Check for merge commits mentioning the issue
+ *
+ * @param issueNumber - The issue number to check
+ * @returns true if the issue's work is merged into main
+ */
+export declare function isIssueMergedIntoMain(issueNumber: number): boolean;
+/**
+ * Lightweight state reconciliation at run start
+ *
+ * Checks issues in `ready_for_merge` state and advances them to `merged`
+ * if their PRs are merged or their branches are in main.
+ *
+ * This prevents re-running already completed issues.
+ *
+ * @param options - Reconciliation options
+ * @returns Result with lists of advanced and still-pending issues
+ */
+export declare function reconcileStateAtStartup(options?: ReconcileOptions): Promise<ReconcileResult>;