@forgrit/shared-contracts-prompt 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog — @forgrit/shared-contracts-prompt
+
+## [0.1.0] — 2026-05-26
+
+### Added — initial public release
+
+- 29 type exports + 1 type alias + 1 runtime enum (ApprovalStatus) across 7 thematic sub-modules:
+  - `./scoring` — RequirementsScoreCard + DimensionScores
+  - `./features` — FeatureSpec, FeatureIntent
+  - `./entities` — EntityDefinition, EntityRelationship
+  - `./requirements` — RequirementsContractV2
+  - `./frozen` — FrozenPromptContract
+  - `./responses` — LLM response shapes
+  - `./quality` — quality-gate result shapes
+
+### Notes
+
+- Source-of-truth reversal package: ForGrit's apps/api uses these via a 22-LOC wildcard re-export shim; the 396 LOC source lives here.
+- Designed for ForGrit's prompt-engine pipeline. External consumers can use the types to build their own prompt-validation layer.
+- Node 20+. Zero hard runtime deps; types-only at runtime except for the ApprovalStatus enum.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForGrit AI <forgritai@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @forgrit/shared-contracts-prompt
+
+> Type-only contracts for ForGrit prompt-engine surfaces — 29 type exports across 7 thematic sub-modules: scoring, features, entities, requirements, frozen, responses, quality.
+
+[![npm version](https://img.shields.io/npm/v/@forgrit/shared-contracts-prompt.svg)](https://www.npmjs.com/package/@forgrit/shared-contracts-prompt)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+> **Status: early-access (v0.x).** Internal-monorepo seam package. Pre-1.0 may include breaking changes in minor bumps.
+
+Source-of-truth reversal package: ForGrit's `apps/api/src/prompt/` consumes these via a 22-LOC wildcard re-export shim; the 396 LOC source lives here.
+
+---
+
+## Install
+
+```bash
+npm install @forgrit/shared-contracts-prompt
+```
+
+Zero hard runtime deps (one runtime export: `ApprovalStatus` enum).
+
+## Sub-modules
+
+```ts
+import { RequirementsScoreCard, DimensionScores } from '@forgrit/shared-contracts-prompt/scoring';
+import { FeatureSpec, FeatureIntent } from '@forgrit/shared-contracts-prompt/features';
+import { EntityDefinition, EntityRelationship } from '@forgrit/shared-contracts-prompt/entities';
+import { RequirementsContractV2 } from '@forgrit/shared-contracts-prompt/requirements';
+import { FrozenPromptContract } from '@forgrit/shared-contracts-prompt/frozen';
+import {} from /* LLM response shapes */ '@forgrit/shared-contracts-prompt/responses';
+import {} from /* quality-gate shapes */ '@forgrit/shared-contracts-prompt/quality';
+```
+
+Or all from the root barrel:
+
+```ts
+import {
+  RequirementsContractV2,
+  FeatureSpec,
+  ApprovalStatus,
+} from '@forgrit/shared-contracts-prompt';
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Sibling packages
+
+- [`@forgrit/contracts`](https://www.npmjs.com/package/@forgrit/contracts) — domain Zod schemas + types
+- [`@forgrit/blueprint`](https://www.npmjs.com/package/@forgrit/blueprint) — app-spec format (consumes these contracts internally)
+- [`@forgrit/shared-contracts-platform`](https://www.npmjs.com/package/@forgrit/shared-contracts-platform)
+- [`@forgrit/shared-contracts-jobs-queue`](https://www.npmjs.com/package/@forgrit/shared-contracts-jobs-queue)

package/dist/_external/app-blueprint-fragments.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @forgrit/shared-contracts-prompt — FOREIGN TYPE FRAGMENTS.
+ *
+ * Plan #5.04 (2026-05-25) — these 2 string unions are DUPLICATED from
+ * apps/api/src/preview/app-blueprint.types.ts. They are NOT re-exports;
+ * they are inline mirrors.
+ *
+ * Why duplicated:
+ *   - prompt-contract.types.ts uses ProjectType + StyleIntent as field
+ *     types on RequirementsContractV2 + UiIntentSpec.
+ *   - The contract package CANNOT import from apps/api/src/* per §1A.b.
+ *   - Contracting app-blueprint.types itself is out of scope here
+ *     (zero lifecycle consumers today per T1 §4; 19 apps/api consumers).
+ *   - The two unions are small (11 + 12 = 23 strings), stable (no
+ *     changes in 6-8 months), and pure enum-style discriminators.
+ *
+ * Drift discipline: any change to ProjectType / StyleIntent in
+ * apps/api/src/preview/app-blueprint.types.ts MUST update this file in
+ * the same commit. README documents the reviewer checklist + the
+ * grep-gate one-liner. When a future plan extracts
+ * @forgrit/shared-contracts-app-blueprint, this file flips from
+ * duplicate to re-export (2-line edit; no consumer-side change).
+ *
+ * Plan #5.04 chose this path (Option A) over Option C (extend scope
+ * to contract app-blueprint.types) because the latter would force a
+ * STYLE_INTENT_LABELS runtime-value escape hatch + 9-property
+ * AppBlueprintContract interface tree that prompt-contract consumers
+ * do not need. Option B (apps/api re-export proxy) was rejected as a
+ * §1A.b violation (it creates apps/api → contract → apps/api cycle).
+ */
+export type ProjectType = 'admin' | 'crm' | 'analytics' | 'commerce' | 'content' | 'collab' | 'saas' | 'public' | 'finance' | 'hr' | 'healthcare';
+export type StyleIntent = 'modern_minimal' | 'enterprise_conservative' | 'neo_banking' | 'glassmorphism' | 'brutalist' | 'editorial_magazine' | 'playful_round' | 'dark_terminal' | 'vibrant_gradient' | 'luxury_serif' | 'retro_soft' | 'developer_docs';
+//# sourceMappingURL=app-blueprint-fragments.d.ts.map

package/dist/_external/app-blueprint-fragments.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * @forgrit/shared-contracts-prompt — FOREIGN TYPE FRAGMENTS.
+ *
+ * Plan #5.04 (2026-05-25) — these 2 string unions are DUPLICATED from
+ * apps/api/src/preview/app-blueprint.types.ts. They are NOT re-exports;
+ * they are inline mirrors.
+ *
+ * Why duplicated:
+ *   - prompt-contract.types.ts uses ProjectType + StyleIntent as field
+ *     types on RequirementsContractV2 + UiIntentSpec.
+ *   - The contract package CANNOT import from apps/api/src/* per §1A.b.
+ *   - Contracting app-blueprint.types itself is out of scope here
+ *     (zero lifecycle consumers today per T1 §4; 19 apps/api consumers).
+ *   - The two unions are small (11 + 12 = 23 strings), stable (no
+ *     changes in 6-8 months), and pure enum-style discriminators.
+ *
+ * Drift discipline: any change to ProjectType / StyleIntent in
+ * apps/api/src/preview/app-blueprint.types.ts MUST update this file in
+ * the same commit. README documents the reviewer checklist + the
+ * grep-gate one-liner. When a future plan extracts
+ * @forgrit/shared-contracts-app-blueprint, this file flips from
+ * duplicate to re-export (2-line edit; no consumer-side change).
+ *
+ * Plan #5.04 chose this path (Option A) over Option C (extend scope
+ * to contract app-blueprint.types) because the latter would force a
+ * STYLE_INTENT_LABELS runtime-value escape hatch + 9-property
+ * AppBlueprintContract interface tree that prompt-contract consumers
+ * do not need. Option B (apps/api re-export proxy) was rejected as a
+ * §1A.b violation (it creates apps/api → contract → apps/api cycle).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=app-blueprint-fragments.js.map

package/dist/entities.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Role + entity surfaces.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:152-180.
+ *
+ * Plan #5.04 (2026-05-25): contracted. Source-of-truth reversal at T6.
+ */
+export interface RoleDefinition {
+    /** Stable snake_case identifier derived deterministically from name (e.g. "admin", "end_user") */
+    id: string;
+    name: string;
+    description: string;
+}
+/** Extended entity field with type information (used by Blueprint Engine and Validator) */
+export interface TypedEntityField {
+    name: string;
+    type: string;
+    required: boolean;
+}
+export interface EntityDefinition {
+    /** Stable snake_case identifier derived deterministically from name (e.g. "lead", "order_item") */
+    id: string;
+    name: string;
+    fields: TypedEntityField[];
+    relationships: string[];
+}
+/** Extended entity definition with typed fields (used by Blueprint Engine) */
+export interface TypedEntityDefinition extends EntityDefinition {
+    typedFields?: TypedEntityField[];
+    isCoreCrud?: boolean;
+}
+//# sourceMappingURL=entities.d.ts.map

package/dist/entities.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Role + entity surfaces.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:152-180.
+ *
+ * Plan #5.04 (2026-05-25): contracted. Source-of-truth reversal at T6.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=entities.js.map

package/dist/features.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Feature + integration surfaces.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:45-58, 182-217.
+ *
+ * Plan #5.04 (2026-05-25): contracted. Source-of-truth reversal at T6.
+ * Subsumes the plan #5.5 wave-2 FM-G bridge surface — after T7, the
+ * bridge file `_prompt-contract-types.ts` becomes a 2-line re-export
+ * from THIS module's `FeatureIntent` + `FeatureSpec` exports.
+ */
+export interface FeatureGraph {
+    core: FeatureNode[];
+    advanced: FeatureNode[];
+    integrations: FeatureNode[];
+    dependencies: Record<string, string[]>;
+}
+export interface FeatureNode {
+    id: string;
+    name: string;
+    complexity: 'simple' | 'moderate' | 'complex';
+    estimatedScreens: number;
+}
+/**
+ * Feature intent — what the user actually DOES with this feature.
+ * Drives screen archetype selection, content templates, and budget weighting.
+ * Distinct from `type` (scope category): type = what it is, intent = how it's used.
+ */
+export type FeatureIntent = 'crud' | 'analytics' | 'workflow' | 'notification' | 'security' | 'integration' | 'marketplace';
+export interface FeatureSpec {
+    id: string;
+    name: string;
+    type: 'core' | 'advanced' | 'integration';
+    /** UX/planning intent — determines screen archetype, not just scope category */
+    intent?: FeatureIntent;
+    /** Classifier confidence 0-1. Used to gate LLM fallback. */
+    intentConfidence?: number;
+    /** How intent was determined: 'rule' (deterministic) or 'llm' (fallback) */
+    intentSource?: 'rule' | 'llm';
+    priority: 'MVP' | 'Next';
+    acceptanceCriteria: string[];
+    dependsOn: string[];
+}
+export interface IntegrationSpec {
+    provider: string;
+    purpose: string;
+    authMethod: string;
+    dataIn: string;
+    dataOut: string;
+}
+//# sourceMappingURL=features.d.ts.map

package/dist/features.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Feature + integration surfaces.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:45-58, 182-217.
+ *
+ * Plan #5.04 (2026-05-25): contracted. Source-of-truth reversal at T6.
+ * Subsumes the plan #5.5 wave-2 FM-G bridge surface — after T7, the
+ * bridge file `_prompt-contract-types.ts` becomes a 2-line re-export
+ * from THIS module's `FeatureIntent` + `FeatureSpec` exports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=features.js.map

package/dist/frozen.d.ts

@@ -0,0 +1,53 @@
+import type { DimensionScores, ScoringExplanation, RiskProfile } from './scoring';
+import type { FeatureGraph } from './features';
+import type { RequirementsContractV2 } from './requirements';
+import type { RequirementsQuality } from './quality';
+/**
+ * Frozen-prompt + combined-final-contract surfaces.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:60-98, 388-396.
+ *
+ * Plan #5.04 (2026-05-25): contracted. Source-of-truth reversal at T6.
+ */
+export interface PromptContract {
+    score: number;
+    scoringExplanation?: ScoringExplanation;
+    criticalGaps?: string[];
+    missingDetails?: string[];
+    missingFields?: string[];
+    dimensionScores: DimensionScores;
+    summary?: string;
+    recommendations?: string[];
+    riskProfile?: RiskProfile;
+    featureGraph?: FeatureGraph;
+}
+export interface FrozenPrompt {
+    promptId: string;
+    version: number;
+    hash: string;
+    originalPrompt: string;
+    contract: PromptContract;
+    requirementsContractV2?: RequirementsContractV2;
+    status: string;
+    frozenAt: string;
+    metadata: {
+        sessionId: string;
+        attempts: number;
+        score: number;
+        dimensionScores: DimensionScores;
+    };
+}
+export interface ExamplePrompt {
+    title: string;
+    prompt: string;
+    expectedScore: number;
+    category?: string;
+}
+export interface CombinedFinalContract {
+    promptScoreContract: PromptContract;
+    requirementsContractV2: RequirementsContractV2 | null;
+    requirementsQuality: RequirementsQuality | null;
+    /** SHA-256 of the normalized RequirementsContractV2 (excluding openQuestions). Stable across re-runs of equivalent prompts. */
+    requirementsHash: string | null;
+}
+//# sourceMappingURL=frozen.d.ts.map

package/dist/frozen.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=frozen.js.map

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './scoring';
+export * from './features';
+export * from './entities';
+export * from './requirements';
+export * from './quality';
+export * from './frozen';
+export * from './responses';
+export * from './_external/app-blueprint-fragments';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,52 @@
+"use strict";
+// @forgrit/shared-contracts-prompt — public surface.
+//
+// Plan #5.04 (2026-05-25) — fourth contract package, sibling to
+// @forgrit/shared-contracts-platform (plan #4.4),
+// @forgrit/shared-contracts-design-composition (plans #4.55 + #4.57),
+// and @forgrit/shared-contracts-jobs-queue (plan #5.05).
+//
+// Surface (29 exports across 7 thematic sub-modules):
+//   - scoring.ts: DimensionScores, ScoringExplanation, RiskProfile
+//   - features.ts: FeatureGraph, FeatureNode, FeatureIntent, FeatureSpec, IntegrationSpec
+//   - entities.ts: RoleDefinition, TypedEntityField, EntityDefinition, TypedEntityDefinition
+//   - requirements.ts: NfrSpec, UiIntentSpec, OpenQuestion, BuildTargetSuggestion, RequirementsContractV2
+//   - quality.ts: ContentBlueprint, KpiDefinition, NavSection, RequirementsQuality
+//   - frozen.ts: PromptContract, FrozenPrompt, ExamplePrompt, CombinedFinalContract
+//   - responses.ts: ApprovalStatus (enum — the ONE runtime export),
+//     FrozenPromptResponse, PromptSessionResponse, PromptAnalysisResponse
+//
+// Foreign types (DUPLICATED, see _external/app-blueprint-fragments.ts):
+//   - ProjectType, StyleIntent — mirrored from apps/api/src/preview/app-blueprint.types
+//
+// Sub-path exports are preferred for tree-shaking. The root barrel
+// exists for convenience + for the apps/api re-export shim (T6).
+//
+// No dependency on @forgrit/shared-contracts-platform OR
+// @forgrit/shared-contracts-design-composition OR
+// @forgrit/shared-contracts-jobs-queue — orthogonal surfaces.
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./scoring"), exports);
+__exportStar(require("./features"), exports);
+__exportStar(require("./entities"), exports);
+__exportStar(require("./requirements"), exports);
+__exportStar(require("./quality"), exports);
+__exportStar(require("./frozen"), exports);
+__exportStar(require("./responses"), exports);
+// Foreign types — duplicated under documented drift discipline.
+__exportStar(require("./_external/app-blueprint-fragments"), exports);
+//# sourceMappingURL=index.js.map

package/dist/quality.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Content blueprint + quality scoring surfaces.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:331-386.
+ *
+ * Plan #5.04 (2026-05-25): contracted. Source-of-truth reversal at T6.
+ */
+export interface ContentBlueprint {
+    /** One compelling, domain-specific tagline (max 10 words) */
+    productTagline?: string;
+    /** 3-5 short feature labels derived from features list */
+    featureHighlights?: string[];
+    /** Realistic social proof statement */
+    socialProofLine?: string;
+    /** Trust signals relevant to domain */
+    trustSignals?: string[];
+    /** 4-6 key metrics for dashboards */
+    kpiDefinitions?: KpiDefinition[];
+    /** Realistic sample names per entity */
+    sampleEntityNames?: Record<string, string[]>;
+    /** Status labels for entity lifecycle */
+    statusLabels?: string[];
+    /** Navigation items matching features + entities */
+    navSections?: NavSection[];
+    /** Domain-specific CTA (e.g., "Log Workout" not "Create") */
+    primaryActionLabel?: string;
+    /** Contextual search hint */
+    searchPlaceholder?: string;
+    /** Friendly empty state message for main entity */
+    emptyStateMessage?: string;
+    /** Dashboard greeting */
+    welcomeMessage?: string;
+}
+export interface KpiDefinition {
+    label: string;
+    format: 'currency' | 'number' | 'percentage' | 'duration';
+    context: 'primary' | 'secondary' | 'trend';
+}
+export interface NavSection {
+    label: string;
+    category: 'main' | 'admin' | 'settings';
+}
+export interface RequirementsQuality {
+    /** 0–100 composite quality score */
+    score: number;
+    /** 0–100: % of required top-level fields that are non-empty */
+    completeness: number;
+    /** 0–100: % of required open questions still unanswered */
+    ambiguity: number;
+    /** Non-blocking quality notes */
+    warnings: string[];
+    /** Critical missing fields that will degrade the design output */
+    blockers: string[];
+    /** Suggestions for improving the prompt (from missing Tier 3 fields) */
+    suggestions?: string[];
+}
+//# sourceMappingURL=quality.d.ts.map

package/dist/quality.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Content blueprint + quality scoring surfaces.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:331-386.
+ *
+ * Plan #5.04 (2026-05-25): contracted. Source-of-truth reversal at T6.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=quality.js.map

package/dist/requirements.d.ts

@@ -0,0 +1,85 @@
+import type { ProjectType, StyleIntent } from './_external/app-blueprint-fragments';
+import type { RoleDefinition, EntityDefinition } from './entities';
+import type { FeatureSpec, IntegrationSpec } from './features';
+import type { ContentBlueprint } from './quality';
+/**
+ * Requirements + UI intent + meta surfaces.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:219-329.
+ *
+ * Note on _external/app-blueprint-fragments: ProjectType + StyleIntent
+ * are duplicated from apps/api/src/preview/app-blueprint.types per plan
+ * #5.04 "ProjectType + StyleIntent decision" (Option A). Drift discipline
+ * in _external/app-blueprint-fragments.ts JSDoc + README.
+ */
+export interface NfrSpec {
+    performanceTarget?: string;
+    securityLevel: 'basic' | 'standard' | 'high';
+    complianceFlags: Array<'HIPAA' | 'GDPR' | 'PCI' | 'SOC2'>;
+    deploymentPreference: 'cloud' | 'self_host' | 'hybrid' | 'unknown';
+}
+export interface UiIntentSpec {
+    navigationPreference: 'sidebar' | 'topbar' | 'split' | 'auto';
+    densityPreference: 'compact' | 'comfortable' | 'spacious';
+    styleIntent: StyleIntent;
+    /** Brand personality — how the product feels emotionally. */
+    brandTone?: 'professional' | 'friendly' | 'bold' | 'calm' | 'playful';
+    /** Primary color mood / palette preference. */
+    colorMood?: 'neutral' | 'warm' | 'cool' | 'vibrant' | 'monochrome';
+    /** Typography personality. */
+    typography?: 'geometric' | 'humanist' | 'slab' | 'mono' | 'serif';
+}
+/**
+ * Input type for a clarification question.
+ * `single_select` → radio buttons (suggestedAnswers required)
+ * `multi_select`  → checkboxes  (suggestedAnswers required)
+ * `short_text`    → free-text input (suggestedAnswers empty)
+ * `yes_no`        → boolean toggle  (suggestedAnswers empty)
+ *
+ * `type` defaults to 'single_select' when suggestedAnswers is non-empty,
+ * 'short_text' otherwise — so existing questions without a type work correctly.
+ *
+ * `mapsTo` is an optional dotted-path hint for deterministic field patching:
+ * e.g. 'authMethods', 'nfrs.securityLevel', 'uiIntent.styleIntent'.
+ * When present, the answer endpoint can apply the patch without text-search heuristics.
+ */
+export interface OpenQuestion {
+    id: string;
+    question: string;
+    suggestedAnswers: string[];
+    required: boolean;
+    /** How to render the answer UI. Defaults based on suggestedAnswers length. */
+    type?: 'single_select' | 'multi_select' | 'short_text' | 'yes_no';
+    /** Dotted path in RequirementsContractV2 this answer should patch. */
+    mapsTo?: string;
+}
+export interface BuildTargetSuggestion {
+    suggestedBuildTarget: 'web-app' | 'backend-api' | 'full-stack' | 'smart-contract';
+    suggestedStack: string;
+    confidence: number;
+    reasons: string[];
+}
+export interface RequirementsContractV2 {
+    version: 2;
+    projectName: string;
+    tagline: string;
+    projectType: ProjectType;
+    mvpGoals: string[];
+    outOfScope: string[];
+    successMetrics?: string[];
+    roles: RoleDefinition[];
+    permissionMatrix: Record<string, string[]>;
+    authRequired: boolean;
+    authMethods: Array<'password' | 'magic_link' | 'sso' | 'mfa' | 'google_oauth' | 'github_oauth' | 'apple_oauth' | 'email'>;
+    entities: EntityDefinition[];
+    primaryEntity: string;
+    seedDataHints?: string[];
+    features: FeatureSpec[];
+    integrations: IntegrationSpec[];
+    nfrs: NfrSpec;
+    uiIntent: UiIntentSpec;
+    openQuestions: OpenQuestion[];
+    buildTargetSuggestion?: BuildTargetSuggestion;
+    contentBlueprint?: ContentBlueprint;
+}
+//# sourceMappingURL=requirements.d.ts.map

package/dist/requirements.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=requirements.js.map

package/dist/responses.d.ts

@@ -0,0 +1,68 @@
+import type { PromptContract } from './frozen';
+import type { RequirementsContractV2 } from './requirements';
+import type { RequirementsQuality } from './quality';
+/**
+ * Response-shaped surfaces for the prompt API.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:100-150.
+ *
+ * THIS MODULE CONTAINS THE ONE RUNTIME EXPORT IN THE PACKAGE — the
+ * ApprovalStatus enum (4-variant string enum). It is the 2nd discrete
+ * runtime export precedent in the @forgrit/shared-contracts-* family
+ * after plan #4.55's variantDecisionKey. README documents the
+ * escape-hatch policy.
+ *
+ * Source-of-truth reversal at T6 means this enum lives canonically in
+ * THIS file; apps/api/src/prompt/schemas/prompt-contract.types.ts
+ * re-exports it via wildcard `export *`. The 5 apps/api consumers of
+ * ApprovalStatus.APPROVED / NEEDS_FORM / DRAFT / FAILED resolve to the
+ * same string values they always have — no behavior change.
+ */
+export declare enum ApprovalStatus {
+    APPROVED = "APPROVED",
+    NEEDS_FORM = "NEEDS_FORM",
+    DRAFT = "DRAFT",
+    FAILED = "FAILED"
+}
+export interface FrozenPromptResponse {
+    promptId: string;
+    sessionId: string;
+    finalPrompt: string;
+    originalPrompt: string;
+    contract: PromptContract;
+    requirementsContractV2?: RequirementsContractV2;
+    requirementsQuality?: RequirementsQuality;
+    requirementsHash?: string;
+    /** Budget confidence 0..1 — derived from RequirementsContractV2 + RequirementsQuality */
+    budgetConfidence?: number;
+    /** Human-readable notes explaining confidence gaps */
+    confidenceNotes?: string[];
+    score: number;
+    version: number;
+    frozenAt: string;
+    parentPromptId: string | null;
+    diffSummary: string | null;
+}
+export interface PromptSessionResponse {
+    sessionId: string;
+    originalPrompt: string;
+    attempts: number;
+    createdAt: string;
+    analyses: PromptAnalysisResponse[];
+}
+export interface PromptAnalysisResponse {
+    status: ApprovalStatus;
+    attempt: number;
+    promptId: string | null;
+    contractDraft: PromptContract;
+    nextActions: string[];
+    metadata: {
+        sessionId: string;
+        modelUsed: string;
+        temperature: number;
+        tokensUsed: number;
+        latencyMs: number;
+        timestamp: string;
+    };
+}
+//# sourceMappingURL=responses.d.ts.map

package/dist/responses.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalStatus = void 0;
+/**
+ * Response-shaped surfaces for the prompt API.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:100-150.
+ *
+ * THIS MODULE CONTAINS THE ONE RUNTIME EXPORT IN THE PACKAGE — the
+ * ApprovalStatus enum (4-variant string enum). It is the 2nd discrete
+ * runtime export precedent in the @forgrit/shared-contracts-* family
+ * after plan #4.55's variantDecisionKey. README documents the
+ * escape-hatch policy.
+ *
+ * Source-of-truth reversal at T6 means this enum lives canonically in
+ * THIS file; apps/api/src/prompt/schemas/prompt-contract.types.ts
+ * re-exports it via wildcard `export *`. The 5 apps/api consumers of
+ * ApprovalStatus.APPROVED / NEEDS_FORM / DRAFT / FAILED resolve to the
+ * same string values they always have — no behavior change.
+ */
+// Existing ApprovalStatus enum
+var ApprovalStatus;
+(function (ApprovalStatus) {
+    ApprovalStatus["APPROVED"] = "APPROVED";
+    ApprovalStatus["NEEDS_FORM"] = "NEEDS_FORM";
+    ApprovalStatus["DRAFT"] = "DRAFT";
+    ApprovalStatus["FAILED"] = "FAILED";
+})(ApprovalStatus || (exports.ApprovalStatus = ApprovalStatus = {}));
+//# sourceMappingURL=responses.js.map

package/dist/scoring.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Scoring + risk surfaces for PromptContract.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:6-43.
+ *
+ * Plan #5.04 (2026-05-25): contracted so lifecycle/* consumers can
+ * satisfy §1A.b without importing from apps/api/src/prompt/schemas at
+ * runtime. Source-of-truth reversal at T6: apps/api source becomes
+ * 1-line re-export from this package.
+ */
+export interface DimensionScores {
+    appType: number;
+    actors: number;
+    features: number;
+    dataDomain: number;
+    technicalStack: number;
+    nfrs: number;
+    uiExpectations: number;
+    integrations: number;
+}
+export interface ScoringExplanation {
+    rawScore: number;
+    normalizedScore: number;
+    maxRawScore: number;
+    breakdown: Array<{
+        dimension: string;
+        score: number;
+        weight: number;
+        contribution: number;
+    }>;
+}
+export interface RiskProfile {
+    scopeRisk: 'low' | 'medium' | 'high';
+    complianceRisk: boolean;
+    securityRisk: 'low' | 'medium' | 'high';
+    costVolatilityRisk: number;
+    riskFactors: string[];
+}
+//# sourceMappingURL=scoring.d.ts.map

package/dist/scoring.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Scoring + risk surfaces for PromptContract.
+ *
+ * MIRRORED FROM: apps/api/src/prompt/schemas/prompt-contract.types.ts:6-43.
+ *
+ * Plan #5.04 (2026-05-25): contracted so lifecycle/* consumers can
+ * satisfy §1A.b without importing from apps/api/src/prompt/schemas at
+ * runtime. Source-of-truth reversal at T6: apps/api source becomes
+ * 1-line re-export from this package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=scoring.js.map

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@forgrit/shared-contracts-prompt",
+  "version": "0.1.0",
+  "description": "Type-only contracts for ForGrit prompt-engine surfaces — 7 sub-modules: scoring, features, entities, requirements, frozen, responses, quality.",
+  "keywords": [
+    "contracts",
+    "types",
+    "prompt-engine",
+    "scoring",
+    "features",
+    "entities",
+    "requirements",
+    "forgrit"
+  ],
+  "license": "MIT",
+  "author": "ForGrit AI <forgritai@gmail.com>",
+  "homepage": "https://github.com/forgrit-ai/forgrit/tree/main/shared/contracts-prompt",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forgrit-ai/forgrit.git",
+    "directory": "shared/contracts-prompt"
+  },
+  "bugs": {
+    "url": "https://github.com/forgrit-ai/forgrit/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./scoring": {
+      "types": "./dist/scoring.d.ts",
+      "default": "./dist/scoring.js"
+    },
+    "./features": {
+      "types": "./dist/features.d.ts",
+      "default": "./dist/features.js"
+    },
+    "./entities": {
+      "types": "./dist/entities.d.ts",
+      "default": "./dist/entities.js"
+    },
+    "./requirements": {
+      "types": "./dist/requirements.d.ts",
+      "default": "./dist/requirements.js"
+    },
+    "./frozen": {
+      "types": "./dist/frozen.d.ts",
+      "default": "./dist/frozen.js"
+    },
+    "./responses": {
+      "types": "./dist/responses.d.ts",
+      "default": "./dist/responses.js"
+    },
+    "./quality": {
+      "types": "./dist/quality.d.ts",
+      "default": "./dist/quality.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@forgrit/tsconfig": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json"
+  }
+}