@neuraloom/contracts 0.0.0-stage → 0.1.22

package/dist/constants/workflow-semantics.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Universal Cognitive Workflow — Step × Kind Semantics Registry
+ *
+ * Maps each canonical `WorkflowStepKind` × `ProjectKind` to its surface label,
+ * description, AI prompt hint, and active gate checks.
+ *
+ * This is the SSOT for orchestration context. Consumers should call
+ * `getStepSemantics(stepKind, projectKind)` rather than reaching into the
+ * raw constant to avoid partial-record gaps.
+ */
+import type { WorkflowStepKind, ProjectKind, StepSemanticConfig } from '../types/project-kind';
+type StepSemanticsMap = Record<WorkflowStepKind, Partial<Record<ProjectKind, StepSemanticConfig>>>;
+export declare const WORKFLOW_STEP_SEMANTICS: StepSemanticsMap;
+/**
+ * Resolve the semantic config for a given step × kind pair.
+ * Falls back to the 'mixed' kind config if no specific override exists.
+ */
+export declare function getStepSemantics(stepKind: WorkflowStepKind, projectKind: ProjectKind): StepSemanticConfig;
+export {};

package/dist/constants/workflow-semantics.js

@@ -0,0 +1,432 @@
+"use strict";
+/**
+ * Universal Cognitive Workflow — Step × Kind Semantics Registry
+ *
+ * Maps each canonical `WorkflowStepKind` × `ProjectKind` to its surface label,
+ * description, AI prompt hint, and active gate checks.
+ *
+ * This is the SSOT for orchestration context. Consumers should call
+ * `getStepSemantics(stepKind, projectKind)` rather than reaching into the
+ * raw constant to avoid partial-record gaps.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKFLOW_STEP_SEMANTICS = void 0;
+exports.getStepSemantics = getStepSemantics;
+exports.WORKFLOW_STEP_SEMANTICS = {
+    // ── intent (was "Specify") ─────────────────────────────────────────────────
+    intent: {
+        software: {
+            label: 'Specify',
+            description: 'Requirements & specifications — user stories, acceptance criteria',
+            promptHint: 'Generate feature specifications with acceptance criteria and constraints.',
+            gateChecks: ['spec_well_formed', 'acceptance_criteria_present'],
+        },
+        fiction: {
+            label: 'Premise',
+            description: 'Core premise, themes, tone, and narrative engine',
+            promptHint: 'Define the central premise, thematic spine, tone, and world-level rules.',
+            gateChecks: ['premise_defined', 'theme_articulated'],
+        },
+        nonfiction: {
+            label: 'Thesis',
+            description: 'Thesis, central argument, audience, and evidence philosophy',
+            promptHint: 'State the thesis, intended reader, evidence standards, and key claims.',
+            gateChecks: ['thesis_stated', 'audience_defined'],
+        },
+        research: {
+            label: 'Research Question',
+            description: 'Research question, hypotheses, scope, and methodology intent',
+            promptHint: 'Articulate the research question, hypotheses, scope, and methodological approach.',
+            gateChecks: ['research_question_defined', 'hypothesis_present'],
+        },
+        documentary: {
+            label: 'Subject',
+            description: 'Documentary subject, angle, and narrative intent',
+            promptHint: 'Define the subject, point of view, and intended narrative arc.',
+            gateChecks: ['subject_defined', 'angle_articulated'],
+        },
+        simulation: {
+            label: 'Model Intent',
+            description: 'Simulation goals, variables, and success conditions',
+            promptHint: 'Describe the system being modelled, observable outputs, and validation criteria.',
+            gateChecks: ['model_goal_defined', 'variables_listed'],
+        },
+        educational: {
+            label: 'Learning Goals',
+            description: 'Learning objectives, target audience, and prerequisite knowledge',
+            promptHint: 'Define learning outcomes (Bloom taxonomy), audience level, and prerequisites.',
+            gateChecks: ['learning_objectives_defined', 'audience_level_set'],
+        },
+        mixed: {
+            label: 'Intent',
+            description: 'Project intent and primary goals',
+            promptHint: 'Describe the overall project intent, primary goals, and success measures.',
+            gateChecks: ['intent_defined'],
+        },
+    },
+    // ── structure (was "Plan") ─────────────────────────────────────────────────
+    structure: {
+        software: {
+            label: 'Plan',
+            description: 'Architecture diagrams, component hierarchy, and dependency map',
+            promptHint: 'Generate system architecture with components, dependencies, and data flow.',
+            gateChecks: ['architecture_present', 'dependencies_mapped'],
+        },
+        fiction: {
+            label: 'Story Structure',
+            description: 'Act/chapter structure, plot beats, and narrative arc',
+            promptHint: 'Outline the act structure, key plot beats, and narrative arc.',
+            gateChecks: ['acts_defined', 'plot_beats_present'],
+        },
+        nonfiction: {
+            label: 'Outline',
+            description: 'Chapter/section outline with argument progression',
+            promptHint: 'Build a chapter outline showing how the argument develops across sections.',
+            gateChecks: ['outline_present', 'argument_progression_coherent'],
+        },
+        research: {
+            label: 'Paper Structure',
+            description: 'IMRaD structure — Introduction, Methods, Results, Discussion',
+            promptHint: 'Define the paper structure following IMRaD or domain-appropriate conventions.',
+            gateChecks: ['structure_follows_convention', 'sections_defined'],
+        },
+        documentary: {
+            label: 'Story Arc',
+            description: 'Segment order, narrative arc, and interview coverage plan',
+            promptHint: 'Plan the documentary segments, arc, and key interviews to include.',
+            gateChecks: ['segments_planned', 'arc_coherent'],
+        },
+        simulation: {
+            label: 'Model Architecture',
+            description: 'Agent/system architecture, state transitions, and parameter space',
+            promptHint: 'Define the simulation architecture, agents/components, and parameter space.',
+            gateChecks: ['architecture_defined', 'state_space_mapped'],
+        },
+        educational: {
+            label: 'Curriculum Structure',
+            description: 'Module and lesson hierarchy with progression logic',
+            promptHint: 'Outline the curriculum: modules, lessons, assessments, and dependencies.',
+            gateChecks: ['modules_defined', 'progression_mapped'],
+        },
+        mixed: {
+            label: 'Structure',
+            description: 'High-level structure and component breakdown',
+            promptHint: 'Define the high-level structure and main components.',
+            gateChecks: ['structure_defined'],
+        },
+    },
+    // ── ontology (was "Schema") ────────────────────────────────────────────────
+    ontology: {
+        software: {
+            label: 'Schema',
+            description: 'Database tables, migrations, RLS policies, and type contracts',
+            promptHint: 'Generate database schema with RLS, migrations, and TypeScript contracts.',
+            gateChecks: ['schema_valid', 'rls_enabled', 'types_exported'],
+        },
+        fiction: {
+            label: 'World Ontology',
+            description: 'Factions, lore systems, symbolic systems, institutions, and cosmology',
+            promptHint: 'Define the world ontology: factions, lore systems, symbolic register, and institutions.',
+            gateChecks: ['lore_consistency', 'factions_defined'],
+        },
+        nonfiction: {
+            label: 'Claim Ontology',
+            description: 'Definitions, load-bearing claims, and concept registry',
+            promptHint: 'Define key terms, load-bearing claims, and their logical dependencies.',
+            gateChecks: ['claim_defined', 'terms_glossarised'],
+        },
+        research: {
+            label: 'Definitions & Variables',
+            description: 'Key terms, variable definitions, and operationalizations',
+            promptHint: 'Define all key terms, variables, and their operational definitions.',
+            gateChecks: ['variables_defined', 'operationalization_present'],
+        },
+        documentary: {
+            label: 'Subject Ontology',
+            description: 'People, organisations, events, and their relationships',
+            promptHint: 'Map the key people, organisations, events, and their relationships.',
+            gateChecks: ['subjects_mapped', 'relationships_defined'],
+        },
+        simulation: {
+            label: 'Entity Ontology',
+            description: 'Entity types, attributes, and interaction rules',
+            promptHint: 'Define all entity types, their attributes, and interaction/transition rules.',
+            gateChecks: ['entities_defined', 'rules_specified'],
+        },
+        educational: {
+            label: 'Concept Map',
+            description: 'Core concepts, definitions, and prerequisite graph',
+            promptHint: 'Define core concepts, their definitions, and prerequisite dependencies.',
+            gateChecks: ['concepts_defined', 'prereq_graph_valid'],
+        },
+        mixed: {
+            label: 'Ontology',
+            description: 'Core entities, definitions, and relationships',
+            promptHint: 'Define the core entities, terms, and their relationships.',
+            gateChecks: ['entities_defined'],
+        },
+    },
+    // ── interaction (was "API") ────────────────────────────────────────────────
+    interaction: {
+        software: {
+            label: 'API',
+            description: 'REST/GraphQL endpoints, request/response contracts, and auth guards',
+            promptHint: 'Generate API endpoints with typed request/response schemas and auth requirements.',
+            gateChecks: ['endpoints_defined', 'auth_guards_present', 'schemas_from_contracts'],
+        },
+        fiction: {
+            label: 'Interaction Systems',
+            description: 'Character interaction protocols, dialogue systems, and agency rules',
+            promptHint: 'Define how characters interact, dialogue registers, and agency constraints.',
+            gateChecks: ['character_agency_defined', 'dialogue_system_present'],
+        },
+        nonfiction: {
+            label: 'Source Registry',
+            description: 'Primary sources, evidence index, and citation protocols',
+            promptHint: 'Build the source registry: primary sources, evidence types, and citation style.',
+            gateChecks: ['sources_registered', 'citation_protocol_defined'],
+        },
+        research: {
+            label: 'Literature Index',
+            description: 'Prior work citations, literature review, and gap analysis',
+            promptHint: 'Catalogue prior work, identify gaps, and map citations.',
+            gateChecks: ['literature_surveyed', 'gaps_identified'],
+        },
+        documentary: {
+            label: 'Interview & Source Plan',
+            description: 'Interview subjects, source materials, and access strategy',
+            promptHint: 'Plan interviews, source materials, and access to primary evidence.',
+            gateChecks: ['interviews_planned', 'sources_identified'],
+        },
+        simulation: {
+            label: 'Interface Contracts',
+            description: 'Input/output contracts, observer hooks, and control API',
+            promptHint: 'Define simulation input/output contracts and observer interfaces.',
+            gateChecks: ['input_contracts_defined', 'observer_hooks_present'],
+        },
+        educational: {
+            label: 'Resource Index',
+            description: 'Learning materials, exercises, and assessment instruments',
+            promptHint: 'Catalogue learning resources, exercise types, and assessment instruments.',
+            gateChecks: ['resources_listed', 'assessments_defined'],
+        },
+        mixed: {
+            label: 'Interaction',
+            description: 'External interfaces, sources, and interaction patterns',
+            promptHint: 'Define external interfaces, data sources, and interaction patterns.',
+            gateChecks: ['interfaces_defined'],
+        },
+    },
+    // ── experience (was "UI") ──────────────────────────────────────────────────
+    experience: {
+        software: {
+            label: 'UI',
+            description: 'Components, layouts, design system, and interaction patterns',
+            promptHint: 'Generate UI components using the design system, accessibility-first.',
+            gateChecks: ['components_conform_to_design_system', 'a11y_check'],
+        },
+        fiction: {
+            label: 'Reader Experience',
+            description: 'Voice, tone, pacing, style guide, and narrative immersion design',
+            promptHint: 'Define voice, tone, pacing guidelines, and immersion techniques.',
+            gateChecks: ['voice_defined', 'style_guide_present'],
+        },
+        nonfiction: {
+            label: 'Style System',
+            description: 'Voice, tone, formatting conventions, and visual hierarchy',
+            promptHint: 'Define the style guide: voice, tone, formatting, and visual conventions.',
+            gateChecks: ['style_defined', 'formatting_consistent'],
+        },
+        research: {
+            label: 'Formatting & Style',
+            description: 'Journal style guide, figure/table conventions, citation format',
+            promptHint: 'Apply journal/venue style guide to all formatting and citation choices.',
+            gateChecks: ['style_guide_applied', 'figures_follow_convention'],
+        },
+        documentary: {
+            label: 'Visual Language',
+            description: 'Visual style, pacing, motion, and sound design guidelines',
+            promptHint: 'Define visual language, pacing, and sound design conventions.',
+            gateChecks: ['visual_language_defined'],
+        },
+        simulation: {
+            label: 'Visualisation Layer',
+            description: 'Dashboard design, chart types, and real-time display conventions',
+            promptHint: 'Design the simulation visualisation layer and output dashboards.',
+            gateChecks: ['visualisation_designed'],
+        },
+        educational: {
+            label: 'Learning Experience',
+            description: 'Content presentation, interaction design, and accessibility',
+            promptHint: 'Design the learner experience: content layout, interactions, and accessibility.',
+            gateChecks: ['ux_designed', 'accessibility_check'],
+        },
+        mixed: {
+            label: 'Experience',
+            description: 'Presentation layer and user/reader experience design',
+            promptHint: 'Design the presentation and experience layer.',
+            gateChecks: ['experience_designed'],
+        },
+    },
+    // ── tasks ──────────────────────────────────────────────────────────────────
+    tasks: {
+        software: {
+            label: 'Tasks',
+            description: 'Break specs into discrete implementation work items',
+            promptHint: 'Decompose specifications into implementation tasks with effort estimates.',
+            gateChecks: ['tasks_have_acceptance_criteria', 'estimates_present'],
+        },
+        fiction: {
+            label: 'Scene Tasks',
+            description: 'Break the outline into scene and chapter writing tasks',
+            promptHint: 'Decompose the story structure into scene-level drafting tasks.',
+            gateChecks: ['scenes_scheduled', 'dependencies_mapped'],
+        },
+        nonfiction: {
+            label: 'Research & Writing Tasks',
+            description: 'Research assignments, drafting tasks, and editorial tasks',
+            promptHint: 'Break the outline into research, drafting, and revision tasks.',
+            gateChecks: ['tasks_cover_outline', 'research_tasks_defined'],
+        },
+        research: {
+            label: 'Research Tasks',
+            description: 'Experiment design, data collection, analysis, and writing tasks',
+            promptHint: 'Decompose the research plan into experiment, data, and writing tasks.',
+            gateChecks: ['methodology_tasks_present', 'writing_tasks_present'],
+        },
+        documentary: {
+            label: 'Production Tasks',
+            description: 'Filming, interview, editing, and post-production tasks',
+            promptHint: 'Plan production tasks: filming, interviews, editing, and delivery.',
+            gateChecks: ['production_tasks_scheduled'],
+        },
+        simulation: {
+            label: 'Build Tasks',
+            description: 'Model implementation, testing, and calibration tasks',
+            promptHint: 'Break model architecture into implementation, testing, and calibration tasks.',
+            gateChecks: ['implementation_tasks_present', 'calibration_tasks_present'],
+        },
+        educational: {
+            label: 'Content Tasks',
+            description: 'Lesson development, exercise creation, and assessment design',
+            promptHint: 'Break curriculum into lesson development and assessment creation tasks.',
+            gateChecks: ['content_tasks_cover_curriculum'],
+        },
+        mixed: {
+            label: 'Tasks',
+            description: 'Decompose goals into discrete work items',
+            promptHint: 'Break project goals into discrete, actionable tasks.',
+            gateChecks: ['tasks_defined'],
+        },
+    },
+    // ── generation (was "Implement") ───────────────────────────────────────────
+    generation: {
+        software: {
+            label: 'Implement',
+            description: 'Generate code, write tests, open pull requests',
+            promptHint: 'Generate production-ready code conforming to the project constitution.',
+            gateChecks: ['contracts_valid', 'tests_pass', 'no_constitutional_violations'],
+        },
+        fiction: {
+            label: 'Draft',
+            description: 'Generate prose: chapters, scenes, lore entries',
+            promptHint: 'Draft the narrative content following the outline, style guide, and world ontology.',
+            gateChecks: ['lore_consistency', 'character_continuity', 'tonal_drift'],
+        },
+        nonfiction: {
+            label: 'Draft Chapters',
+            description: 'Generate chapter drafts from outline and source evidence',
+            promptHint: 'Draft chapters grounding every claim in registered sources.',
+            gateChecks: ['source_quality', 'claim_support', 'hallucination_risk'],
+        },
+        research: {
+            label: 'Draft Sections',
+            description: 'Generate paper sections from structure and collected data',
+            promptHint: 'Draft paper sections following the approved structure and methodology.',
+            gateChecks: ['methodology_valid', 'citation_integrity', 'hallucination_risk'],
+        },
+        documentary: {
+            label: 'Produce',
+            description: 'Generate scripts, narration, and edit instructions',
+            promptHint: 'Generate documentary scripts, narration, and segment instructions.',
+            gateChecks: ['factual_accuracy', 'source_quality'],
+        },
+        simulation: {
+            label: 'Build Model',
+            description: 'Generate simulation code, agents, and calibration scripts',
+            promptHint: 'Implement the simulation model per the entity ontology and architecture.',
+            gateChecks: ['model_validity', 'runtime_healthy', 'determinism_check'],
+        },
+        educational: {
+            label: 'Develop Content',
+            description: 'Generate lessons, exercises, and assessments',
+            promptHint: 'Develop lesson content, exercises, and assessments per learning objectives.',
+            gateChecks: ['learning_objective_coverage', 'accuracy_check'],
+        },
+        mixed: {
+            label: 'Generate',
+            description: 'Generate primary deliverable content',
+            promptHint: 'Generate the primary deliverable content following project intent.',
+            gateChecks: ['output_complete'],
+        },
+    },
+    // ── review ─────────────────────────────────────────────────────────────────
+    review: {
+        software: {
+            label: 'Review',
+            description: 'Post-deployment validation, compliance audit, and retrospective',
+            promptHint: 'Validate deployment, run compliance audit, and generate retrospective.',
+            gateChecks: ['deployment_ready', 'contracts_valid', 'tests_pass'],
+        },
+        fiction: {
+            label: 'Editorial Review',
+            description: 'Continuity audit, tonal consistency, and structural integrity check',
+            promptHint: 'Audit for lore contradictions, character continuity breaks, and tonal drift.',
+            gateChecks: ['lore_consistency', 'character_continuity', 'tonal_drift', 'narrative_pacing'],
+        },
+        nonfiction: {
+            label: 'Editorial Review',
+            description: 'Claim audit, source verification, and argument coherence check',
+            promptHint: 'Verify claims against sources, check argument coherence, flag contradictions.',
+            gateChecks: ['source_quality', 'claim_support', 'contradiction_analysis', 'hallucination_risk'],
+        },
+        research: {
+            label: 'Peer Review',
+            description: 'Methodology review, statistical check, and citation integrity audit',
+            promptHint: 'Review methodology, check statistical claims, and verify citation integrity.',
+            gateChecks: ['methodology_valid', 'citation_integrity', 'hallucination_risk'],
+        },
+        documentary: {
+            label: 'Editorial Review',
+            description: 'Factual accuracy check, narrative coherence, and pacing review',
+            promptHint: 'Verify factual claims, assess narrative coherence, and review pacing.',
+            gateChecks: ['factual_accuracy', 'narrative_arc', 'source_quality'],
+        },
+        simulation: {
+            label: 'Validation',
+            description: 'Model validation against expected behaviour and edge cases',
+            promptHint: 'Validate simulation outputs against expected behaviour and edge cases.',
+            gateChecks: ['model_validity', 'edge_case_handling', 'determinism_check'],
+        },
+        educational: {
+            label: 'Quality Review',
+            description: 'Learning objective coverage check, accuracy review, and accessibility audit',
+            promptHint: 'Verify learning objective coverage, content accuracy, and accessibility.',
+            gateChecks: ['learning_objective_coverage', 'accuracy_check', 'accessibility_check'],
+        },
+        mixed: {
+            label: 'Review',
+            description: 'Quality review and coherence audit',
+            promptHint: 'Review output quality, coherence, and goal alignment.',
+            gateChecks: ['output_complete'],
+        },
+    },
+};
+/**
+ * Resolve the semantic config for a given step × kind pair.
+ * Falls back to the 'mixed' kind config if no specific override exists.
+ */
+function getStepSemantics(stepKind, projectKind) {
+    const byStep = exports.WORKFLOW_STEP_SEMANTICS[stepKind];
+    return byStep[projectKind] ?? byStep['mixed'];
+}

package/dist/constants/workflow-vocabulary.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Workflow vocabulary — SSOT for step label overrides per project.kind.
+ * software uses canonical WORKFLOW_STEPS labels (no overrides needed).
+ * Writing kinds share a base vocabulary with per-kind specialization.
+ */
+import type { WorkflowKind } from './workflow-registry';
+export type StepVocab = {
+    title: string;
+    description: string;
+};
+/** @deprecated Use KIND_STEP_VOCAB or getStepVocabulary() instead. Kept for migration. */
+export declare const WRITING_STEP_VOCAB: Record<string, StepVocab>;
+export declare const WRITING_PHASE_NAMES: Record<number, string>;
+/**
+ * Resolve step vocabulary for a given project kind and step id.
+ * Returns the most specific override available, falling back to the base writing vocab,
+ * then to undefined (caller should use WORKFLOW_STEPS canonical label).
+ */
+export declare function getStepVocabulary(kind: WorkflowKind, stepId: string): StepVocab | undefined;
+/**
+ * Resolve phase names for a given project kind.
+ */
+export declare function getPhaseNames(kind: WorkflowKind): Record<number, string>;