gswd 1.0.0 → 1.1.0

package/dist/lib/specify-agents.d.ts

@@ -0,0 +1,120 @@
+/**
+ * GSWD Specify Agents Module — Agent definitions, sequential-then-parallel orchestration
+ *
+ * Provides the 3 specify agents: journey-mapper (sequential), then
+ * architecture-drafter + integrations-checker (parallel).
+ *
+ * Follows the imagine-agents.ts pattern but with phased orchestration.
+ *
+ * Schema: GSWD_SPEC.md Section 8.3, Section 11.1
+ */
+import type { Journey, FunctionalRequirement } from './specify-journeys.js';
+import type { OnAgentComplete } from './imagine-agents.js';
+export interface SpecifyAgentDefinition {
+    /** Agent name matching file name (without .md) */
+    name: string;
+    /** Path to agent definition file */
+    definitionPath: string;
+    /** Phase: 'sequential' runs first, 'parallel' runs after sequential completes */
+    phase: 'sequential' | 'parallel';
+    /** Minimum headings expected in agent output */
+    requiredHeadings: string[];
+}
+export interface Integration {
+    /** Integration ID in I-001 format */
+    id: string;
+    /** Integration name */
+    name: string;
+    /** Steps to set up the integration */
+    setupSteps: string[];
+    /** Authentication method */
+    authMethod: string;
+    /** Monthly cost or quota description */
+    costQuota: string;
+    /** Fallback if integration unavailable */
+    fallback: string;
+    /** Approval status — MANDATORY field */
+    status: 'approved' | 'deferred with fallback' | 'rejected';
+}
+export interface ArchitectureComponent {
+    /** Component ID in C-001 format */
+    id: string;
+    /** Component name */
+    name: string;
+    /** What this component does */
+    responsibility: string;
+    /** Other C-XXX IDs this depends on */
+    dependencies: string[];
+    /** FR-XXX IDs this component implements */
+    linkedFRs: string[];
+}
+export interface AgentResult {
+    /** Agent name */
+    agent: string;
+    /** Agent output content */
+    content: string;
+    /** Completion status */
+    status: 'complete' | 'failed';
+    /** Error message if failed */
+    error?: string;
+    /** Execution time in milliseconds */
+    duration_ms?: number;
+}
+export type SpawnFn = (prompt: string) => Promise<string>;
+/**
+ * The 3 specify agents from GSWD_SPEC Section 11.1.
+ * journey-mapper runs first (sequential); others run after (parallel).
+ */
+export declare const SPECIFY_AGENTS: SpecifyAgentDefinition[];
+export interface SpecifyAgentContext {
+    /** DECISIONS.md content */
+    decisionsContent: string;
+    /** IMAGINE.md content (optional) */
+    imagineContent?: string;
+    /** Extracted journeys (available after journey-mapper) */
+    journeys?: Journey[];
+    /** Extracted FRs (available after FR extraction) */
+    frs?: FunctionalRequirement[];
+    /** Auto policy config content */
+    autoPolicy?: string;
+}
+/**
+ * Build the prompt for a specify agent.
+ *
+ * - journey-mapper: gets DECISIONS.md + IMAGINE.md
+ * - architecture-drafter: gets journeys + FRs + DECISIONS.md
+ * - integrations-checker: gets journeys + FRs + DECISIONS.md + auto policy
+ */
+export declare function buildSpecifyAgentPrompt(agent: SpecifyAgentDefinition, context: SpecifyAgentContext): string;
+/**
+ * Orchestrate specify agents with sequential-then-parallel pattern.
+ *
+ * Phase 1 (sequential): Run journey-mapper, wait for completion.
+ * Phase 2 (parallel): Run architecture-drafter + integrations-checker concurrently.
+ *
+ * Failed agents are marked with status: 'failed' but do not crash orchestration.
+ *
+ * @param agents - Agent definitions (defaults to SPECIFY_AGENTS)
+ * @param context - Shared context for prompt building
+ * @param spawnFn - Function that spawns an agent (Task() wrapper)
+ * @returns All agent results including failures
+ */
+export declare function orchestrateSpecifyAgents(agents: SpecifyAgentDefinition[], context: SpecifyAgentContext, spawnFn: SpawnFn, onComplete?: OnAgentComplete): Promise<AgentResult[]>;
+/**
+ * Valid integration status values.
+ */
+export declare const VALID_INTEGRATION_STATUSES: readonly ["approved", "deferred with fallback", "rejected"];
+/**
+ * Validate that an integration has all required fields including mandatory Status.
+ */
+export declare function validateIntegration(integration: Integration): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Validate that a component has correct ID format and required fields.
+ */
+export declare function validateComponent(component: ArchitectureComponent): {
+    valid: boolean;
+    errors: string[];
+};

package/dist/lib/specify-agents.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * GSWD Specify Agents Module — Agent definitions, sequential-then-parallel orchestration
+ *
+ * Provides the 3 specify agents: journey-mapper (sequential), then
+ * architecture-drafter + integrations-checker (parallel).
+ *
+ * Follows the imagine-agents.ts pattern but with phased orchestration.
+ *
+ * Schema: GSWD_SPEC.md Section 8.3, Section 11.1
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_INTEGRATION_STATUSES = exports.SPECIFY_AGENTS = void 0;
+exports.buildSpecifyAgentPrompt = buildSpecifyAgentPrompt;
+exports.orchestrateSpecifyAgents = orchestrateSpecifyAgents;
+exports.validateIntegration = validateIntegration;
+exports.validateComponent = validateComponent;
+const fs = __importStar(require("node:fs"));
+const render_js_1 = require("./render.js");
+// ─── Agent Definitions ───────────────────────────────────────────────────────
+/**
+ * The 3 specify agents from GSWD_SPEC Section 11.1.
+ * journey-mapper runs first (sequential); others run after (parallel).
+ */
+exports.SPECIFY_AGENTS = [
+    {
+        name: 'journey-mapper',
+        definitionPath: 'agents/gswd/journey-mapper.md',
+        phase: 'sequential',
+        requiredHeadings: ['### J-'],
+    },
+    {
+        name: 'architecture-drafter',
+        definitionPath: 'agents/gswd/architecture-drafter.md',
+        phase: 'parallel',
+        requiredHeadings: ['### Components', '### Data Model'],
+    },
+    {
+        name: 'integrations-checker',
+        definitionPath: 'agents/gswd/integrations-checker.md',
+        phase: 'parallel',
+        requiredHeadings: ['## Integrations'],
+    },
+];
+/**
+ * Build the prompt for a specify agent.
+ *
+ * - journey-mapper: gets DECISIONS.md + IMAGINE.md
+ * - architecture-drafter: gets journeys + FRs + DECISIONS.md
+ * - integrations-checker: gets journeys + FRs + DECISIONS.md + auto policy
+ */
+function buildSpecifyAgentPrompt(agent, context) {
+    let definition;
+    try {
+        definition = fs.readFileSync(agent.definitionPath, 'utf-8');
+    }
+    catch {
+        definition = `Agent: ${agent.name}\nRole: Specify agent`;
+    }
+    const sections = [definition];
+    // Always include decisions
+    if (context.decisionsContent) {
+        sections.push(`<decisions>\n${context.decisionsContent}\n</decisions>`);
+    }
+    switch (agent.name) {
+        case 'journey-mapper':
+            if (context.imagineContent) {
+                sections.push(`<imagine>\n${context.imagineContent}\n</imagine>`);
+            }
+            break;
+        case 'architecture-drafter':
+            if (context.frs && context.frs.length > 0) {
+                const frSummary = context.frs
+                    .map((fr) => `- ${fr.id}: ${fr.description} [${fr.scope}/${fr.priority}]`)
+                    .join('\n');
+                sections.push(`<functional_requirements>\n${frSummary}\n</functional_requirements>`);
+            }
+            if (context.journeys && context.journeys.length > 0) {
+                const journeySummary = context.journeys
+                    .map((j) => `- ${j.id}: ${j.name} (${j.type}, ${j.steps.length} steps)`)
+                    .join('\n');
+                sections.push(`<journeys>\n${journeySummary}\n</journeys>`);
+            }
+            break;
+        case 'integrations-checker':
+            if (context.frs && context.frs.length > 0) {
+                const frSummary = context.frs
+                    .map((fr) => `- ${fr.id}: ${fr.description} [${fr.scope}/${fr.priority}]`)
+                    .join('\n');
+                sections.push(`<functional_requirements>\n${frSummary}\n</functional_requirements>`);
+            }
+            if (context.journeys && context.journeys.length > 0) {
+                const journeySummary = context.journeys
+                    .map((j) => `- ${j.id}: ${j.name} (${j.type}, ${j.steps.length} steps)`)
+                    .join('\n');
+                sections.push(`<journeys>\n${journeySummary}\n</journeys>`);
+            }
+            if (context.autoPolicy) {
+                sections.push(`<auto_policy>\n${context.autoPolicy}\n</auto_policy>`);
+            }
+            break;
+    }
+    sections.push(`Produce your output now. Include all required headings: ${agent.requiredHeadings.join(', ')}.`);
+    return sections.join('\n\n');
+}
+// ─── Orchestration ───────────────────────────────────────────────────────────
+/**
+ * Orchestrate specify agents with sequential-then-parallel pattern.
+ *
+ * Phase 1 (sequential): Run journey-mapper, wait for completion.
+ * Phase 2 (parallel): Run architecture-drafter + integrations-checker concurrently.
+ *
+ * Failed agents are marked with status: 'failed' but do not crash orchestration.
+ *
+ * @param agents - Agent definitions (defaults to SPECIFY_AGENTS)
+ * @param context - Shared context for prompt building
+ * @param spawnFn - Function that spawns an agent (Task() wrapper)
+ * @returns All agent results including failures
+ */
+async function orchestrateSpecifyAgents(agents, context, spawnFn, onComplete) {
+    const results = [];
+    // Phase 1: Sequential agents
+    const sequentialAgents = agents.filter((a) => a.phase === 'sequential');
+    for (const agent of sequentialAgents) {
+        const result = await runSingleAgent(agent, context, spawnFn);
+        results.push(result);
+        if (onComplete) {
+            onComplete({
+                agent: result.agent,
+                headline: result.status === 'complete'
+                    ? (0, render_js_1.extractHeadline)(result.content, result.agent)
+                    : (result.error || 'Agent failed'),
+                status: result.status,
+            });
+        }
+    }
+    // Phase 2: Parallel agents
+    const parallelAgents = agents.filter((a) => a.phase === 'parallel');
+    if (parallelAgents.length > 0) {
+        const parallelPromises = parallelAgents.map(async (agent) => {
+            const result = await runSingleAgent(agent, context, spawnFn);
+            if (onComplete) {
+                onComplete({
+                    agent: result.agent,
+                    headline: result.status === 'complete'
+                        ? (0, render_js_1.extractHeadline)(result.content, result.agent)
+                        : (result.error || 'Agent failed'),
+                    status: result.status,
+                });
+            }
+            return result;
+        });
+        const parallelResults = await Promise.all(parallelPromises);
+        results.push(...parallelResults);
+    }
+    return results;
+}
+/**
+ * Run a single agent and return its result.
+ */
+async function runSingleAgent(agent, context, spawnFn) {
+    const start = Date.now();
+    try {
+        const prompt = buildSpecifyAgentPrompt(agent, context);
+        const content = await spawnFn(prompt);
+        return {
+            agent: agent.name,
+            content,
+            status: 'complete',
+            duration_ms: Date.now() - start,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            agent: agent.name,
+            content: '',
+            status: 'failed',
+            error: message,
+            duration_ms: Date.now() - start,
+        };
+    }
+}
+// ─── Integration Validation ──────────────────────────────────────────────────
+/**
+ * Valid integration status values.
+ */
+exports.VALID_INTEGRATION_STATUSES = [
+    'approved',
+    'deferred with fallback',
+    'rejected',
+];
+/**
+ * Validate that an integration has all required fields including mandatory Status.
+ */
+function validateIntegration(integration) {
+    const errors = [];
+    // ID format
+    if (!/^I-\d{3,}$/.test(integration.id)) {
+        errors.push(`Invalid integration ID format: ${integration.id} (expected I-XXX)`);
+    }
+    // Name non-empty
+    if (!integration.name || integration.name.trim() === '') {
+        errors.push(`Integration ${integration.id} has empty name`);
+    }
+    // Status is mandatory and must be a valid value
+    if (!exports.VALID_INTEGRATION_STATUSES.includes(integration.status)) {
+        errors.push(`Integration ${integration.id} has invalid status: "${integration.status}" (expected: ${exports.VALID_INTEGRATION_STATUSES.join(', ')})`);
+    }
+    // Deferred integrations must have a fallback
+    if (integration.status === 'deferred with fallback') {
+        if (!integration.fallback || integration.fallback.trim() === '') {
+            errors.push(`Integration ${integration.id} is deferred but has no fallback`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Validate that a component has correct ID format and required fields.
+ */
+function validateComponent(component) {
+    const errors = [];
+    // ID format
+    if (!/^C-\d{3,}$/.test(component.id)) {
+        errors.push(`Invalid component ID format: ${component.id} (expected C-XXX)`);
+    }
+    // Name non-empty
+    if (!component.name || component.name.trim() === '') {
+        errors.push(`Component ${component.id} has empty name`);
+    }
+    // Responsibility non-empty
+    if (!component.responsibility || component.responsibility.trim() === '') {
+        errors.push(`Component ${component.id} has empty responsibility`);
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/lib/specify-journeys.d.ts

@@ -0,0 +1,124 @@
+/**
+ * GSWD Specify Journeys Module — Journey generation, FR extraction, cross-linking
+ *
+ * Produces journey structures and extracts functional requirements from journey steps.
+ * Bidirectional cross-linking: journeys reference FR IDs, FRs reference source journeys.
+ *
+ * Schema: GSWD_SPEC.md Section 6.1 (ID formats), 6.2 (scope tagging), 8.3 (specify workflow)
+ */
+export type JourneyType = 'onboarding' | 'core_action' | 'view_results' | 'settings' | 'error_states' | 'empty_states';
+export interface FailureMode {
+    /** Concise scenario description (1-2 sentences max) */
+    scenario: string;
+    /** How the system handles this failure */
+    handling: string;
+}
+export interface JourneyStep {
+    /** Step number (1-based) */
+    number: number;
+    /** User action description */
+    action: string;
+    /** FR-XXX IDs derived from this step (populated during extraction) */
+    frIds: string[];
+}
+export interface Journey {
+    /** Journey ID in J-001 format */
+    id: string;
+    /** Human-readable journey name */
+    name: string;
+    /** Journey type category */
+    type: JourneyType;
+    /** Conditions that must be true before journey starts */
+    preconditions: string[];
+    /** Ordered user action steps (5-8 for main, 3+ for error/empty) */
+    steps: JourneyStep[];
+    /** Successful completion outcome */
+    success: string;
+    /** Failure scenarios (>= 2 required) */
+    failureModes: FailureMode[];
+    /** Single assertable test statements (>= 1 required) */
+    acceptanceTests: string[];
+    /** FR-XXX IDs linked to this journey (populated after extraction) */
+    linkedFRs: string[];
+    /** NFR-XXX IDs linked to this journey (populated later) */
+    linkedNFRs: string[];
+}
+export interface FunctionalRequirement {
+    /** FR ID in FR-001 format */
+    id: string;
+    /** What this requirement describes */
+    description: string;
+    /** Scope tag: v1/v2/out */
+    scope: 'v1' | 'v2' | 'out';
+    /** Priority: P0 (blocks core), P1 (required v1), P2 (enhances) */
+    priority: 'P0' | 'P1' | 'P2';
+    /** J-XXX IDs of source journeys */
+    sourceJourneys: string[];
+    /** "J-XXX step N" format references */
+    sourceSteps: string[];
+}
+export interface TraceabilityEntry {
+    /** FR ID */
+    frId: string;
+    /** FR description */
+    description: string;
+    /** Formatted journey references: "J-001 (step 3), J-002 (step 1)" */
+    journeyRefs: string[];
+}
+/**
+ * All 6 required journey types from GSWD_SPEC Section 8.3.
+ */
+export declare const JOURNEY_TYPES: {
+    type: JourneyType;
+    displayName: string;
+}[];
+/**
+ * Assign scope based on journey type.
+ * Heuristic from CONTEXT.md locked decisions:
+ * - core_action/onboarding → v1
+ * - error_states/empty_states → v1 (required for polish)
+ * - view_results → v1
+ * - settings → v1 (default; caller can override to v2 for non-essential)
+ */
+export declare function assignScope(journeyType: JourneyType): 'v1' | 'v2' | 'out';
+/**
+ * Assign priority based on journey type.
+ * Heuristic from CONTEXT.md locked decisions:
+ * - core_action/onboarding → P0 (blocks core journey)
+ * - error_states/empty_states/view_results/settings → P1 (required for complete v1)
+ */
+export declare function assignPriority(journeyType: JourneyType): 'P0' | 'P1' | 'P2';
+/**
+ * Create a journey skeleton with proper ID and empty arrays.
+ */
+export declare function generateJourneyStructure(type: JourneyType, journeyNumber: number): Journey;
+/**
+ * Validate a journey meets all structural requirements.
+ */
+export declare function validateJourney(journey: Journey): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Extract FRs from journeys. Each journey step maps to at least 1 FR.
+ * Populates bidirectional cross-links:
+ * - Each step.frIds gets the generated FR IDs
+ * - Each journey.linkedFRs gets all FR IDs from its steps
+ * - Each FR.sourceJourneys references the parent journey
+ * - Each FR.sourceSteps references "J-XXX step N"
+ *
+ * Duplicate step descriptions merge into a single FR with multiple sources.
+ */
+export declare function extractFRsFromJourneys(journeys: Journey[]): FunctionalRequirement[];
+/**
+ * Build traceability map for SPEC.md traceability table.
+ * Each entry maps an FR to its source journeys.
+ */
+export declare function buildTraceabilityMap(frs: FunctionalRequirement[]): TraceabilityEntry[];
+/**
+ * Validate FR coverage: every journey step has FRs, every FR has sources.
+ */
+export declare function validateFRCoverage(journeys: Journey[], frs: FunctionalRequirement[]): {
+    valid: boolean;
+    errors: string[];
+};