@gordon.gan/specflow 1.4.3-beta → 1.4.6-beta

package/dist/core/approval/index-schema.d.ts

@@ -0,0 +1,244 @@
+import { z } from 'zod';
+import type { ApprovalIndex } from './types.js';
+export declare const approvalIndexSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"specflow.approval.index/v1">;
+    change: z.ZodString;
+    generated_at: z.ZodEffects<z.ZodString, string, unknown>;
+    mode: z.ZodDefault<z.ZodEnum<["segmented", "monolithic"]>>;
+    ui_in_scope: z.ZodDefault<z.ZodBoolean>;
+    db_in_scope: z.ZodDefault<z.ZodBoolean>;
+    api_in_scope: z.ZodDefault<z.ZodBoolean>;
+    optional: z.ZodDefault<z.ZodObject<{
+        s5: z.ZodDefault<z.ZodBoolean>;
+        s7: z.ZodDefault<z.ZodBoolean>;
+        s8: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        s5: boolean;
+        s7: boolean;
+        s8: boolean;
+    }, {
+        s5?: boolean | undefined;
+        s7?: boolean | undefined;
+        s8?: boolean | undefined;
+    }>>;
+    parts_order: z.ZodArray<z.ZodString, "many">;
+    design_points: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    decisions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    tables: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        action: z.ZodString;
+        part: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        name: string;
+        action: string;
+        part: string;
+    }, {
+        id: string;
+        name: string;
+        action: string;
+        part: string;
+    }>, "many">>;
+    interfaces: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        short: z.ZodString;
+        change: z.ZodString;
+        part: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+    }, {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+    }>, "many">>;
+    pages: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        route: z.ZodString;
+        apis: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        part: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        part: string;
+        route: string;
+        apis: string[];
+    }, {
+        id: string;
+        part: string;
+        route: string;
+        apis?: string[] | undefined;
+    }>, "many">>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        part: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        part: string;
+    }, {
+        id: string;
+        part: string;
+    }>, "many">>;
+    batching: z.ZodDefault<z.ZodObject<{
+        tables_per_call: z.ZodDefault<z.ZodNumber>;
+        interfaces_per_call: z.ZodDefault<z.ZodNumber>;
+        pages_per_call: z.ZodDefault<z.ZodNumber>;
+        capabilities_per_call: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        tables_per_call: number;
+        interfaces_per_call: number;
+        pages_per_call: number;
+        capabilities_per_call: number;
+    }, {
+        tables_per_call?: number | undefined;
+        interfaces_per_call?: number | undefined;
+        pages_per_call?: number | undefined;
+        capabilities_per_call?: number | undefined;
+    }>>;
+    conventions: z.ZodDefault<z.ZodObject<{
+        architecture: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        database: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        api: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        frontend: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        architecture?: string[] | undefined;
+        api?: string[] | undefined;
+        database?: string[] | undefined;
+        frontend?: string[] | undefined;
+    }, {
+        architecture?: string[] | undefined;
+        api?: string[] | undefined;
+        database?: string[] | undefined;
+        frontend?: string[] | undefined;
+    }>>;
+    meta: z.ZodOptional<z.ZodObject<{
+        language: z.ZodOptional<z.ZodString>;
+        tech_stack: z.ZodOptional<z.ZodString>;
+        project_mode: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        language?: string | undefined;
+        tech_stack?: string | undefined;
+        project_mode?: string | undefined;
+    }, {
+        language?: string | undefined;
+        tech_stack?: string | undefined;
+        project_mode?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    schema: "specflow.approval.index/v1";
+    conventions: {
+        architecture?: string[] | undefined;
+        api?: string[] | undefined;
+        database?: string[] | undefined;
+        frontend?: string[] | undefined;
+    };
+    change: string;
+    generated_at: string;
+    mode: "segmented" | "monolithic";
+    ui_in_scope: boolean;
+    db_in_scope: boolean;
+    api_in_scope: boolean;
+    optional: {
+        s5: boolean;
+        s7: boolean;
+        s8: boolean;
+    };
+    parts_order: string[];
+    design_points: string[];
+    decisions: string[];
+    tables: {
+        id: string;
+        name: string;
+        action: string;
+        part: string;
+    }[];
+    interfaces: {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+    }[];
+    pages: {
+        id: string;
+        part: string;
+        route: string;
+        apis: string[];
+    }[];
+    capabilities: {
+        id: string;
+        part: string;
+    }[];
+    batching: {
+        tables_per_call: number;
+        interfaces_per_call: number;
+        pages_per_call: number;
+        capabilities_per_call: number;
+    };
+    meta?: {
+        language?: string | undefined;
+        tech_stack?: string | undefined;
+        project_mode?: string | undefined;
+    } | undefined;
+}, {
+    schema: "specflow.approval.index/v1";
+    change: string;
+    parts_order: string[];
+    conventions?: {
+        architecture?: string[] | undefined;
+        api?: string[] | undefined;
+        database?: string[] | undefined;
+        frontend?: string[] | undefined;
+    } | undefined;
+    generated_at?: unknown;
+    mode?: "segmented" | "monolithic" | undefined;
+    ui_in_scope?: boolean | undefined;
+    db_in_scope?: boolean | undefined;
+    api_in_scope?: boolean | undefined;
+    optional?: {
+        s5?: boolean | undefined;
+        s7?: boolean | undefined;
+        s8?: boolean | undefined;
+    } | undefined;
+    design_points?: string[] | undefined;
+    decisions?: string[] | undefined;
+    tables?: {
+        id: string;
+        name: string;
+        action: string;
+        part: string;
+    }[] | undefined;
+    interfaces?: {
+        id: string;
+        part: string;
+        short: string;
+        change: string;
+    }[] | undefined;
+    pages?: {
+        id: string;
+        part: string;
+        route: string;
+        apis?: string[] | undefined;
+    }[] | undefined;
+    capabilities?: {
+        id: string;
+        part: string;
+    }[] | undefined;
+    batching?: {
+        tables_per_call?: number | undefined;
+        interfaces_per_call?: number | undefined;
+        pages_per_call?: number | undefined;
+        capabilities_per_call?: number | undefined;
+    } | undefined;
+    meta?: {
+        language?: string | undefined;
+        tech_stack?: string | undefined;
+        project_mode?: string | undefined;
+    } | undefined;
+}>;
+export declare function parseApprovalIndex(raw: unknown): ApprovalIndex;
+/** Returns true when segmented fast-path (monolithic) is allowed. */
+export declare function isLightweightApproval(index: ApprovalIndex): boolean;
+export declare function shouldForceSegmented(index: ApprovalIndex): boolean;

package/dist/core/approval/index-schema.js

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+const tableRefSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    action: z.string().min(1),
+    part: z.string().min(1),
+});
+const interfaceRefSchema = z.object({
+    id: z.string().min(1),
+    short: z.string().min(1),
+    change: z.string().min(1),
+    part: z.string().min(1),
+});
+const pageRefSchema = z.object({
+    id: z.string().min(1),
+    route: z.string().min(1),
+    apis: z.array(z.string()).default([]),
+    part: z.string().min(1),
+});
+const capabilityRefSchema = z.object({
+    id: z.string().min(1),
+    part: z.string().min(1),
+});
+export const approvalIndexSchema = z.object({
+    schema: z.literal('specflow.approval.index/v1'),
+    change: z.string().min(1),
+    generated_at: z.preprocess((val) => (val instanceof Date ? val.toISOString() : val), z.string().min(1)),
+    mode: z.enum(['segmented', 'monolithic']).default('segmented'),
+    ui_in_scope: z.boolean().default(false),
+    db_in_scope: z.boolean().default(false),
+    api_in_scope: z.boolean().default(false),
+    optional: z
+        .object({
+        s5: z.boolean().default(false),
+        s7: z.boolean().default(false),
+        s8: z.boolean().default(false),
+    })
+        .default({ s5: false, s7: false, s8: false }),
+    parts_order: z.array(z.string().min(1)).min(1),
+    design_points: z.array(z.string()).default([]),
+    decisions: z.array(z.string()).default([]),
+    tables: z.array(tableRefSchema).default([]),
+    interfaces: z.array(interfaceRefSchema).default([]),
+    pages: z.array(pageRefSchema).default([]),
+    capabilities: z.array(capabilityRefSchema).default([]),
+    batching: z
+        .object({
+        tables_per_call: z.number().int().positive().default(3),
+        interfaces_per_call: z.number().int().positive().default(3),
+        pages_per_call: z.number().int().positive().default(3),
+        capabilities_per_call: z.number().int().positive().default(1),
+    })
+        .default({
+        tables_per_call: 3,
+        interfaces_per_call: 3,
+        pages_per_call: 3,
+        capabilities_per_call: 1,
+    }),
+    conventions: z
+        .object({
+        architecture: z.array(z.string()).optional(),
+        database: z.array(z.string()).optional(),
+        api: z.array(z.string()).optional(),
+        frontend: z.array(z.string()).optional(),
+    })
+        .default({}),
+    meta: z
+        .object({
+        language: z.string().optional(),
+        tech_stack: z.string().optional(),
+        project_mode: z.string().optional(),
+    })
+        .optional(),
+});
+export function parseApprovalIndex(raw) {
+    return approvalIndexSchema.parse(raw);
+}
+/** Returns true when segmented fast-path (monolithic) is allowed. */
+export function isLightweightApproval(index) {
+    return (index.tables.length <= 2 &&
+        index.interfaces.length <= 3 &&
+        index.pages.length <= 2 &&
+        !index.optional.s5);
+}
+export function shouldForceSegmented(index) {
+    if (index.mode === 'monolithic') {
+        return false;
+    }
+    return !isLightweightApproval(index);
+}

package/dist/core/approval/index.d.ts

@@ -0,0 +1,4 @@
+export type { ApprovalAssembleResult, ApprovalDiagnostic, ApprovalIndex, ApprovalManifest, ApprovalGenerationMode, } from './types.js';
+export { parseApprovalIndex, isLightweightApproval, shouldForceSegmented, approvalIndexSchema, } from './index-schema.js';
+export { getChangeDirectory, getApprovalWorkspaceDir, getApprovalIndexPath, getApprovalManifestPath, getApprovalPartsDir, getApprovalPartPath, getApprovalOutputPath, getApprovalAnalysisPath, } from './paths.js';
+export { assembleApprovalDocument, readApprovalIndex, readApprovalManifest, } from './assemble.js';

package/dist/core/approval/index.js

@@ -0,0 +1,3 @@
+export { parseApprovalIndex, isLightweightApproval, shouldForceSegmented, approvalIndexSchema, } from './index-schema.js';
+export { getChangeDirectory, getApprovalWorkspaceDir, getApprovalIndexPath, getApprovalManifestPath, getApprovalPartsDir, getApprovalPartPath, getApprovalOutputPath, getApprovalAnalysisPath, } from './paths.js';
+export { assembleApprovalDocument, readApprovalIndex, readApprovalManifest, } from './assemble.js';

package/dist/core/approval/paths.d.ts

@@ -0,0 +1,8 @@
+export declare function getChangeDirectory(projectRoot: string, changeName: string): string;
+export declare function getApprovalWorkspaceDir(changeDir: string): string;
+export declare function getApprovalIndexPath(changeDir: string): string;
+export declare function getApprovalManifestPath(changeDir: string): string;
+export declare function getApprovalPartsDir(changeDir: string): string;
+export declare function getApprovalPartPath(changeDir: string, partId: string): string;
+export declare function getApprovalOutputPath(changeDir: string): string;
+export declare function getApprovalAnalysisPath(changeDir: string): string;

package/dist/core/approval/paths.js

@@ -0,0 +1,28 @@
+import { join } from 'node:path';
+import { validateChangeName } from '../../utils/change-utils.js';
+const CHANGES_REL = 'specflow/changes';
+export function getChangeDirectory(projectRoot, changeName) {
+    validateChangeName(changeName);
+    return join(projectRoot, CHANGES_REL, changeName);
+}
+export function getApprovalWorkspaceDir(changeDir) {
+    return join(changeDir, 'approval');
+}
+export function getApprovalIndexPath(changeDir) {
+    return join(getApprovalWorkspaceDir(changeDir), 'index.yaml');
+}
+export function getApprovalManifestPath(changeDir) {
+    return join(getApprovalWorkspaceDir(changeDir), 'manifest.json');
+}
+export function getApprovalPartsDir(changeDir) {
+    return join(getApprovalWorkspaceDir(changeDir), 'parts');
+}
+export function getApprovalPartPath(changeDir, partId) {
+    return join(getApprovalPartsDir(changeDir), `${partId}.md`);
+}
+export function getApprovalOutputPath(changeDir) {
+    return join(changeDir, 'approval.md');
+}
+export function getApprovalAnalysisPath(changeDir) {
+    return join(getApprovalWorkspaceDir(changeDir), 'analysis.json');
+}

package/dist/core/approval/types.d.ts

@@ -0,0 +1,92 @@
+export type ApprovalGenerationMode = 'segmented' | 'monolithic';
+export type ApprovalPartStatus = 'draft' | 'ok' | 'retry';
+export interface ApprovalOptionalChapters {
+    readonly s5: boolean;
+    readonly s7: boolean;
+    readonly s8: boolean;
+}
+export interface ApprovalBatching {
+    readonly tables_per_call: number;
+    readonly interfaces_per_call: number;
+    readonly pages_per_call: number;
+    readonly capabilities_per_call: number;
+}
+export interface ApprovalTableRef {
+    readonly id: string;
+    readonly name: string;
+    readonly action: string;
+    readonly part: string;
+}
+export interface ApprovalInterfaceRef {
+    readonly id: string;
+    readonly short: string;
+    readonly change: string;
+    readonly part: string;
+}
+export interface ApprovalPageRef {
+    readonly id: string;
+    readonly route: string;
+    readonly apis: readonly string[];
+    readonly part: string;
+}
+export interface ApprovalCapabilityRef {
+    readonly id: string;
+    readonly part: string;
+}
+export interface ApprovalConventionsResolved {
+    readonly architecture?: readonly string[];
+    readonly database?: readonly string[];
+    readonly api?: readonly string[];
+    readonly frontend?: readonly string[];
+}
+export interface ApprovalIndex {
+    readonly schema: 'specflow.approval.index/v1';
+    readonly change: string;
+    readonly generated_at: string;
+    readonly mode: ApprovalGenerationMode;
+    readonly ui_in_scope: boolean;
+    readonly db_in_scope: boolean;
+    readonly api_in_scope: boolean;
+    readonly optional: ApprovalOptionalChapters;
+    readonly parts_order: readonly string[];
+    readonly design_points: readonly string[];
+    readonly decisions: readonly string[];
+    readonly tables: readonly ApprovalTableRef[];
+    readonly interfaces: readonly ApprovalInterfaceRef[];
+    readonly pages: readonly ApprovalPageRef[];
+    readonly capabilities: readonly ApprovalCapabilityRef[];
+    readonly batching: ApprovalBatching;
+    readonly conventions: ApprovalConventionsResolved;
+    readonly meta?: {
+        readonly language?: string;
+        readonly tech_stack?: string;
+        readonly project_mode?: string;
+    };
+}
+export interface ApprovalManifestPart {
+    readonly id: string;
+    readonly path: string;
+    readonly status: ApprovalPartStatus;
+    readonly sha256?: string;
+    readonly updated_at?: string;
+}
+export interface ApprovalManifest {
+    readonly schema: 'specflow.approval.manifest/v1';
+    readonly change: string;
+    readonly parts: readonly ApprovalManifestPart[];
+    readonly assembled_at?: string;
+    readonly approval_sha256?: string;
+}
+export type ApprovalDiagnosticSeverity = 'error' | 'warning';
+export interface ApprovalDiagnostic {
+    readonly code: string;
+    readonly severity: ApprovalDiagnosticSeverity;
+    readonly message: string;
+    readonly part?: string;
+}
+export interface ApprovalAssembleResult {
+    readonly markdown?: string;
+    readonly outputPath?: string;
+    readonly diagnostics: readonly ApprovalDiagnostic[];
+    readonly ok: boolean;
+}

package/dist/core/approval/types.js

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

package/dist/core/project-config.d.ts

@@ -6,6 +6,9 @@ export interface NormalizedReference {
     readonly id: string;
     readonly remote?: string;
 }
+export declare const CONVENTION_TOPICS: readonly ["architecture", "api", "database", "frontend"];
+export type ConventionTopic = (typeof CONVENTION_TOPICS)[number];
+export type ProjectConventions = Readonly<Partial<Record<ConventionTopic, readonly string[]>>>;
 export interface ParsedProjectConfig {
     readonly schema: string;
     readonly context?: string;
@@ -14,6 +17,7 @@ export interface ParsedProjectConfig {
     readonly workflowUpstream?: string;
     readonly store?: string;
     readonly references: readonly NormalizedReference[];
+    readonly conventions: ProjectConventions;
     readonly diagnostics: readonly Diagnostic[];
 }
 export declare function parseProjectConfig(raw: unknown): ParsedProjectConfig;

package/dist/core/project-config.js

@@ -12,6 +12,12 @@ const ReferenceObjectSchema = z
     remote: z.string().url().optional(),
 })
     .strict();
+export const CONVENTION_TOPICS = [
+    'architecture',
+    'api',
+    'database',
+    'frontend',
+];
 function referenceDiagnostic(message, target) {
     return {
         severity: 'warning',
@@ -155,6 +161,48 @@ export function parseProjectConfig(raw) {
             fix: `Add '${workflowUpstream}' to specflow/config.yaml references.`,
         });
     }
+    const conventions = {};
+    if (record.conventions !== undefined) {
+        const conventionsRaw = typeof record.conventions === 'object' &&
+            record.conventions !== null &&
+            !Array.isArray(record.conventions)
+            ? record.conventions
+            : undefined;
+        if (!conventionsRaw) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'invalid_conventions_config',
+                message: 'Project conventions must be an object of topic → path arrays.',
+                target: 'config.conventions',
+                fix: 'Use conventions.architecture|api|database|frontend: [relative/path.md].',
+            });
+        }
+        else {
+            for (const topic of CONVENTION_TOPICS) {
+                const value = conventionsRaw[topic];
+                if (value === undefined) {
+                    continue;
+                }
+                if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+                    diagnostics.push({
+                        severity: 'error',
+                        code: 'invalid_conventions_topic',
+                        message: `conventions.${topic} must be an array of relative file path strings.`,
+                        target: `config.conventions.${topic}`,
+                        fix: `Set conventions.${topic} to e.g. ['docs/engineering/${topic}.md'].`,
+                    });
+                    continue;
+                }
+                const paths = value
+                    .map((item) => item.trim())
+                    .filter((item) => item.length > 0)
+                    .slice(0, 3);
+                if (paths.length > 0) {
+                    conventions[topic] = paths;
+                }
+            }
+        }
+    }
     return {
         schema,
         context,
@@ -163,6 +211,7 @@ export function parseProjectConfig(raw) {
         workflowUpstream,
         store,
         references,
+        conventions,
         diagnostics,
     };
 }

package/dist/core/project-conventions.d.ts

@@ -0,0 +1,15 @@
+import { type ConventionTopic, type ProjectConventions } from './project-config.js';
+export type IdeFlavor = 'cursor' | 'claude' | 'codex';
+/**
+ * Resolves project convention files for an approval topic.
+ * Priority: config conventions.<topic> → repo-neutral docs.
+ * IDE-specific rule/skill globs are documented for the agent to scan; this helper
+ * covers the deterministic, config + neutral paths used in tests and tooling.
+ */
+export declare function resolveProjectConventionPaths(input: {
+    readonly projectRoot: string;
+    readonly topic: ConventionTopic;
+    readonly conventions?: ProjectConventions;
+}): readonly string[];
+export declare function listConventionTopics(): readonly ConventionTopic[];
+export declare function neutralCandidatesFor(topic: ConventionTopic): readonly string[];

package/dist/core/project-conventions.js

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { CONVENTION_TOPICS, } from './project-config.js';
+const NEUTRAL_CANDIDATES = {
+    architecture: [
+        'docs/engineering/architecture.md',
+        '.specflow/conventions/architecture.md',
+        'ARCHITECTURE.md',
+    ],
+    api: [
+        'docs/api/guidelines.md',
+        'docs/engineering/api.md',
+        '.specflow/conventions/api.md',
+    ],
+    database: [
+        'docs/db/conventions.md',
+        'docs/engineering/database.md',
+        '.specflow/conventions/database.md',
+    ],
+    frontend: [
+        'docs/frontend/conventions.md',
+        'docs/frontend/patterns.md',
+        'docs/frontend/testing.md',
+        'docs/engineering/frontend.md',
+        '.specflow/conventions/frontend.md',
+        'agent_docs/tech_stack.md',
+        'agent_docs/code_patterns.md',
+        'agent_docs/testing.md',
+    ],
+};
+const MAX_FILES_PER_TOPIC = 3;
+function existingRelative(projectRoot, relativePaths) {
+    const found = [];
+    for (const relative of relativePaths) {
+        const normalized = relative.replace(/^\.\//, '').replace(/\\/g, '/');
+        if (!normalized || normalized.includes('..')) {
+            continue;
+        }
+        if (existsSync(join(projectRoot, ...normalized.split('/')))) {
+            found.push(normalized);
+        }
+        if (found.length >= MAX_FILES_PER_TOPIC) {
+            break;
+        }
+    }
+    return found;
+}
+/**
+ * Resolves project convention files for an approval topic.
+ * Priority: config conventions.<topic> → repo-neutral docs.
+ * IDE-specific rule/skill globs are documented for the agent to scan; this helper
+ * covers the deterministic, config + neutral paths used in tests and tooling.
+ */
+export function resolveProjectConventionPaths(input) {
+    const configured = input.conventions?.[input.topic];
+    if (configured && configured.length > 0) {
+        return existingRelative(input.projectRoot, configured.slice(0, MAX_FILES_PER_TOPIC));
+    }
+    return existingRelative(input.projectRoot, NEUTRAL_CANDIDATES[input.topic]);
+}
+export function listConventionTopics() {
+    return CONVENTION_TOPICS;
+}
+export function neutralCandidatesFor(topic) {
+    return NEUTRAL_CANDIDATES[topic];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gordon.gan/specflow",
-  "version": "1.4.3-beta",
+  "version": "1.4.6-beta",
   "type": "module",
   "description": "SpecFlow — unified spec-driven development: OpenSpec planning + Superpowers execution in one CLI and cross-IDE workflow",
   "keywords": [