@pellux/goodvibes-sdk 0.26.10 → 0.27.0

package/dist/_internal/platform/knowledge/map.js

@@ -0,0 +1,235 @@
+import { isGeneratedKnowledgeSource, } from './generated-projections.js';
+export function renderKnowledgeMap(state, options = {}) {
+    const limit = sanitizeMapLimit(options.limit);
+    const nodes = state.nodes
+        .filter((node) => node.status !== 'stale')
+        .sort(compareRecordTitle)
+        .slice(0, limit);
+    let remaining = Math.max(0, limit - nodes.length);
+    const sources = options.includeSources === false
+        ? []
+        : state.sources
+            .filter((source) => source.status !== 'stale')
+            .filter((source) => options.includeGenerated !== false || !isGeneratedKnowledgeSource(source))
+            .sort(compareRecordTitle)
+            .slice(0, remaining);
+    remaining = Math.max(0, remaining - sources.length);
+    const issues = options.includeIssues
+        ? (state.issues ?? [])
+            .filter((issue) => issue.status === 'open')
+            .sort(compareIssue)
+            .slice(0, remaining)
+        : [];
+    const mapNodes = layoutMapNodes([
+        ...nodes.map((node) => ({
+            id: node.id,
+            recordKind: 'node',
+            kind: node.kind,
+            title: node.title,
+            ...(node.summary ? { summary: node.summary } : {}),
+            x: 0,
+            y: 0,
+            radius: radiusForNodeKind(node.kind),
+            metadata: node.metadata,
+        })),
+        ...sources.map((source) => ({
+            id: source.id,
+            recordKind: 'source',
+            kind: sourceKind(source),
+            title: source.title ?? source.sourceUri ?? source.id,
+            ...(source.summary ? { summary: source.summary } : {}),
+            x: 0,
+            y: 0,
+            radius: 11,
+            metadata: source.metadata,
+        })),
+        ...issues.map((issue) => ({
+            id: issue.id,
+            recordKind: 'issue',
+            kind: issue.code,
+            title: issue.message,
+            x: 0,
+            y: 0,
+            radius: 10,
+            metadata: issue.metadata,
+        })),
+    ]);
+    const nodeIds = new Set(mapNodes.map((node) => node.id));
+    const visibleEdges = state.edges
+        .filter((edge) => nodeIds.has(edge.fromId) && nodeIds.has(edge.toId))
+        .map((edge) => ({
+        id: edge.id,
+        fromId: edge.fromId,
+        toId: edge.toId,
+        relation: edge.relation,
+        weight: edge.weight,
+        metadata: edge.metadata,
+    }));
+    const width = 1280;
+    const height = 920;
+    const title = options.title ?? state.title ?? 'Knowledge Map';
+    return {
+        ok: true,
+        ...(options.spaceId ? { spaceId: options.spaceId } : {}),
+        title,
+        generatedAt: Date.now(),
+        width,
+        height,
+        nodeCount: mapNodes.length,
+        edgeCount: visibleEdges.length,
+        nodes: mapNodes,
+        edges: visibleEdges,
+        svg: renderMapSvg({ width, height, title, nodes: mapNodes, edges: visibleEdges }),
+    };
+}
+function layoutMapNodes(nodes) {
+    const width = 1280;
+    const height = 920;
+    const centerX = width / 2;
+    const centerY = height / 2;
+    const groups = new Map();
+    for (const node of nodes) {
+        const ring = ringForKind(node.kind, node.recordKind);
+        const group = groups.get(ring);
+        if (group) {
+            group.push(node);
+        }
+        else {
+            groups.set(ring, [node]);
+        }
+    }
+    const laidOut = [];
+    for (const [ring, group] of [...groups.entries()].sort((left, right) => left[0] - right[0])) {
+        const radius = ring === 0 ? 0 : 110 + ring * 90;
+        const offset = ring * 0.41;
+        group.forEach((node, index) => {
+            const angle = group.length === 1
+                ? -Math.PI / 2 + offset
+                : -Math.PI / 2 + offset + (Math.PI * 2 * index) / group.length;
+            laidOut.push({
+                ...node,
+                x: Math.round(centerX + Math.cos(angle) * radius),
+                y: Math.round(centerY + Math.sin(angle) * radius),
+            });
+        });
+    }
+    return laidOut;
+}
+function renderMapSvg(input) {
+    const byId = new Map(input.nodes.map((node) => [node.id, node]));
+    const edgeLines = input.edges.map((edge) => {
+        const from = byId.get(edge.fromId);
+        const to = byId.get(edge.toId);
+        if (!from || !to)
+            return '';
+        return `<line x1="${from.x}" y1="${from.y}" x2="${to.x}" y2="${to.y}" stroke="rgba(57,74,97,0.35)" stroke-width="1.3"><title>${escapeXml(edge.relation)}</title></line>`;
+    }).join('\n');
+    const nodeShapes = input.nodes.map((node) => {
+        const color = colorForKind(node.kind, node.recordKind);
+        const label = truncateLabel(node.title, node.recordKind === 'source' ? 28 : 24);
+        const shape = node.recordKind === 'source'
+            ? `<rect x="${node.x - 58}" y="${node.y - 17}" width="116" height="34" rx="11" fill="${color.fill}" stroke="${color.stroke}" stroke-width="1.4" />`
+            : `<circle cx="${node.x}" cy="${node.y}" r="${node.radius}" fill="${color.fill}" stroke="${color.stroke}" stroke-width="1.6" />`;
+        const textY = node.recordKind === 'source' ? node.y + 4 : node.y + node.radius + 18;
+        return `<g class="node">
+  <title>${escapeXml(node.title)} (${escapeXml(node.kind)})</title>
+  ${shape}
+  <text x="${node.x}" y="${textY}" text-anchor="middle">${escapeXml(label)}</text>
+</g>`;
+    }).join('\n');
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${input.width}" height="${input.height}" viewBox="0 0 ${input.width} ${input.height}" role="img" aria-label="${escapeXml(input.title)}">
+<defs>
+  <radialGradient id="knowledgeMapBg" cx="50%" cy="46%" r="70%">
+    <stop offset="0%" stop-color="#f7f4ec" />
+    <stop offset="60%" stop-color="#e9eef0" />
+    <stop offset="100%" stop-color="#dde6df" />
+  </radialGradient>
+  <filter id="softShadow" x="-20%" y="-20%" width="140%" height="140%">
+    <feDropShadow dx="0" dy="6" stdDeviation="8" flood-color="#27313a" flood-opacity="0.14"/>
+  </filter>
+</defs>
+<style>
+  text { font-family: "Avenir Next", "Trebuchet MS", sans-serif; font-size: 12px; fill: #263238; paint-order: stroke; stroke: rgba(247,244,236,0.76); stroke-width: 3px; stroke-linejoin: round; }
+  .node { filter: url(#softShadow); }
+</style>
+<rect width="100%" height="100%" fill="url(#knowledgeMapBg)" />
+<g>${edgeLines}</g>
+<g>${nodeShapes}</g>
+</svg>`;
+}
+function sourceKind(source) {
+    if (isGeneratedKnowledgeSource(source)) {
+        const projectionKind = typeof source.metadata.projectionKind === 'string'
+            ? source.metadata.projectionKind
+            : 'page';
+        return `generated_${projectionKind.replace(/[^a-z0-9]+/gi, '_')}`;
+    }
+    return source.sourceType;
+}
+function ringForKind(kind, recordKind) {
+    if (recordKind === 'issue')
+        return 7;
+    if (recordKind === 'source')
+        return kind.startsWith('generated_') ? 5 : 6;
+    if (kind === 'ha_home')
+        return 0;
+    if (kind === 'domain' || kind === 'topic' || kind === 'ha_area' || kind === 'ha_room')
+        return 1;
+    if (kind === 'ha_device' || kind === 'ha_device_passport')
+        return 2;
+    if (kind === 'ha_entity')
+        return 3;
+    return 4;
+}
+function radiusForNodeKind(kind) {
+    if (kind === 'ha_home' || kind === 'domain')
+        return 30;
+    if (kind === 'topic' || kind === 'ha_area' || kind === 'ha_room')
+        return 23;
+    if (kind === 'ha_device')
+        return 18;
+    if (kind === 'ha_entity')
+        return 13;
+    return 12;
+}
+function colorForKind(kind, recordKind) {
+    if (recordKind === 'issue')
+        return { fill: '#f4c7c3', stroke: '#9f3f36' };
+    if (recordKind === 'source') {
+        if (kind.startsWith('generated_'))
+            return { fill: '#fff1c7', stroke: '#b98920' };
+        return { fill: '#dceef5', stroke: '#3f839c' };
+    }
+    if (kind === 'ha_home' || kind === 'domain')
+        return { fill: '#284b63', stroke: '#102a3a' };
+    if (kind === 'topic' || kind === 'ha_area' || kind === 'ha_room')
+        return { fill: '#9ec5ab', stroke: '#49765a' };
+    if (kind === 'ha_device')
+        return { fill: '#f2b880', stroke: '#a86028' };
+    if (kind === 'ha_entity')
+        return { fill: '#b8c7e0', stroke: '#5d7092' };
+    if (kind === 'ha_device_passport')
+        return { fill: '#f6df90', stroke: '#9a7725' };
+    return { fill: '#d7d0c2', stroke: '#70695e' };
+}
+function compareRecordTitle(left, right) {
+    return (left.title ?? left.id).localeCompare(right.title ?? right.id) || left.id.localeCompare(right.id);
+}
+function compareIssue(left, right) {
+    return left.code.localeCompare(right.code) || left.id.localeCompare(right.id);
+}
+function sanitizeMapLimit(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 500;
+    return Math.max(1, Math.min(1000, Math.trunc(value)));
+}
+function truncateLabel(value, limit) {
+    return value.length <= limit ? value : `${value.slice(0, Math.max(1, limit - 1))}...`;
+}
+function escapeXml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;');
+}

package/dist/_internal/platform/knowledge/project-planning/helpers.d.ts

@@ -0,0 +1,17 @@
+import type { ProjectPlanningSpaceInput } from './types.js';
+export declare const PROJECT_PLANNING_CONNECTOR_ID = "goodvibes-project-planning";
+export declare const PROJECT_PLANNING_TAG = "project-planning";
+export type ProjectPlanningArtifactKind = 'state' | 'decision' | 'language';
+export interface ResolvedProjectPlanningSpace {
+    readonly projectId: string;
+    readonly knowledgeSpaceId: string;
+}
+export declare function projectPlanningProjectIdFromPath(path: string): string;
+export declare function resolveProjectPlanningSpace(input?: ProjectPlanningSpaceInput, defaultProjectId?: string): ResolvedProjectPlanningSpace;
+export declare function projectIdFromSpace(spaceId: string): string;
+export declare function projectPlanningCanonicalUri(spaceId: string, kind: ProjectPlanningArtifactKind, id: string): string;
+export declare function projectPlanningSourceId(spaceId: string, kind: ProjectPlanningArtifactKind, id: string): string;
+export declare function projectPlanningArtifactSummary(kind: ProjectPlanningArtifactKind, value: unknown): string;
+export declare function stablePlanningId(prefix: string, value: string): string;
+export declare function readPlanningMetadataObject(value: unknown): Record<string, unknown>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/_internal/platform/knowledge/project-planning/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/project-planning/helpers.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAGV,yBAAyB,EAE1B,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,6BAA6B,+BAA+B,CAAC;AAC1E,eAAO,MAAM,oBAAoB,qBAAqB,CAAC;AAEvD,MAAM,MAAM,2BAA2B,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAE5E,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED,wBAAgB,2BAA2B,CACzC,KAAK,GAAE,yBAA8B,EACrC,gBAAgB,SAAY,GAC3B,4BAA4B,CAe9B;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,2BAA2B,EACjC,EAAE,EAAE,MAAM,GACT,MAAM,CAER;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,2BAA2B,EACjC,EAAE,EAAE,MAAM,GACT,MAAM,CAGR;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,2BAA2B,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAWxG;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtE;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIlF"}

package/dist/_internal/platform/knowledge/project-planning/helpers.js

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+import { basename, resolve } from 'node:path';
+import { PROJECT_KNOWLEDGE_SPACE_PREFIX, isProjectKnowledgeSpace, normalizeKnowledgeSpaceId, normalizeProjectId, normalizeSpaceComponent, projectKnowledgeSpaceId, } from '../spaces.js';
+export const PROJECT_PLANNING_CONNECTOR_ID = 'goodvibes-project-planning';
+export const PROJECT_PLANNING_TAG = 'project-planning';
+export function projectPlanningProjectIdFromPath(path) {
+    const resolved = resolve(path);
+    const name = normalizeSpaceComponent(basename(resolved) || 'project');
+    const digest = createHash('sha256').update(resolved).digest('hex').slice(0, 10);
+    return `${name}-${digest}`;
+}
+export function resolveProjectPlanningSpace(input = {}, defaultProjectId = 'default') {
+    const explicitSpace = typeof input.knowledgeSpaceId === 'string'
+        ? normalizeKnowledgeSpaceId(input.knowledgeSpaceId)
+        : '';
+    if (explicitSpace && isProjectKnowledgeSpace(explicitSpace)) {
+        return {
+            knowledgeSpaceId: explicitSpace,
+            projectId: projectIdFromSpace(explicitSpace),
+        };
+    }
+    const projectId = normalizeProjectId(input.projectId ?? defaultProjectId);
+    return {
+        projectId,
+        knowledgeSpaceId: projectKnowledgeSpaceId(projectId),
+    };
+}
+export function projectIdFromSpace(spaceId) {
+    const normalized = normalizeKnowledgeSpaceId(spaceId);
+    if (!normalized.startsWith(PROJECT_KNOWLEDGE_SPACE_PREFIX)) {
+        return normalizeProjectId(normalized);
+    }
+    return normalizeProjectId(normalized.slice(PROJECT_KNOWLEDGE_SPACE_PREFIX.length));
+}
+export function projectPlanningCanonicalUri(spaceId, kind, id) {
+    return `goodvibes://planning/${encodeURIComponent(spaceId)}/${kind}/${encodeURIComponent(id)}`;
+}
+export function projectPlanningSourceId(spaceId, kind, id) {
+    const digest = createHash('sha256').update(`${spaceId}:${kind}:${id}`).digest('hex').slice(0, 16);
+    return `project-planning-${kind}-${digest}`;
+}
+export function projectPlanningArtifactSummary(kind, value) {
+    if (kind === 'state') {
+        const state = value;
+        return state.goal ? `Planning state for ${state.goal}` : 'Project planning state.';
+    }
+    if (kind === 'decision') {
+        const decision = value;
+        return decision.decision ? `${decision.title ?? 'Decision'}: ${decision.decision}` : 'Project planning decision record.';
+    }
+    const language = value;
+    return `Project language artifact with ${language.terms?.length ?? 0} terms and ${language.ambiguities?.length ?? 0} resolved ambiguities.`;
+}
+export function stablePlanningId(prefix, value) {
+    const normalized = normalizeSpaceComponent(value);
+    if (normalized !== 'default')
+        return normalized;
+    const digest = createHash('sha256').update(value || prefix).digest('hex').slice(0, 10);
+    return `${prefix}-${digest}`;
+}
+export function readPlanningMetadataObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}

package/dist/_internal/platform/knowledge/project-planning/index.d.ts

@@ -0,0 +1,6 @@
+export { ProjectPlanningService } from './service.js';
+export type { ProjectPlanningServiceOptions } from './service.js';
+export { PROJECT_PLANNING_CONNECTOR_ID, PROJECT_PLANNING_TAG, projectPlanningCanonicalUri, projectPlanningProjectIdFromPath, projectPlanningSourceId, resolveProjectPlanningSpace, } from './helpers.js';
+export { evaluateProjectPlanningReadiness } from './readiness.js';
+export type { ProjectPlanningAgentAssignment, ProjectPlanningAmbiguity, ProjectPlanningDecision, ProjectPlanningDecisionRecordInput, ProjectPlanningDecisionResult, ProjectPlanningDecisionsResult, ProjectPlanningDecisionStatus, ProjectPlanningDependency, ProjectPlanningEvaluateInput, ProjectPlanningEvaluation, ProjectPlanningGap, ProjectPlanningGapKind, ProjectPlanningGapSeverity, ProjectPlanningGateStatus, ProjectPlanningLanguageArtifact, ProjectPlanningLanguageResult, ProjectPlanningLanguageUpsertInput, ProjectPlanningQuestion, ProjectPlanningQuestionStatus, ProjectPlanningReadiness, ProjectPlanningSpaceInput, ProjectPlanningState, ProjectPlanningStateResult, ProjectPlanningStateUpsertInput, ProjectPlanningStatus, ProjectPlanningTask, ProjectPlanningTaskStatus, ProjectPlanningTerm, ProjectPlanningVerificationGate, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/knowledge/project-planning/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/project-planning/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,YAAY,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EACL,6BAA6B,EAC7B,oBAAoB,EACpB,2BAA2B,EAC3B,gCAAgC,EAChC,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gCAAgC,EAAE,MAAM,gBAAgB,CAAC;AAClE,YAAY,EACV,8BAA8B,EAC9B,wBAAwB,EACxB,uBAAuB,EACvB,kCAAkC,EAClC,6BAA6B,EAC7B,8BAA8B,EAC9B,6BAA6B,EAC7B,yBAAyB,EACzB,4BAA4B,EAC5B,yBAAyB,EACzB,kBAAkB,EAClB,sBAAsB,EACtB,0BAA0B,EAC1B,yBAAyB,EACzB,+BAA+B,EAC/B,6BAA6B,EAC7B,kCAAkC,EAClC,uBAAuB,EACvB,6BAA6B,EAC7B,wBAAwB,EACxB,yBAAyB,EACzB,oBAAoB,EACpB,0BAA0B,EAC1B,+BAA+B,EAC/B,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,mBAAmB,EACnB,+BAA+B,GAChC,MAAM,YAAY,CAAC"}

package/dist/_internal/platform/knowledge/project-planning/index.js

@@ -0,0 +1,3 @@
+export { ProjectPlanningService } from './service.js';
+export { PROJECT_PLANNING_CONNECTOR_ID, PROJECT_PLANNING_TAG, projectPlanningCanonicalUri, projectPlanningProjectIdFromPath, projectPlanningSourceId, resolveProjectPlanningSpace, } from './helpers.js';
+export { evaluateProjectPlanningReadiness } from './readiness.js';

package/dist/_internal/platform/knowledge/project-planning/readiness.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectPlanningEvaluation, ProjectPlanningState } from './types.js';
+export declare function evaluateProjectPlanningReadiness(state: ProjectPlanningState): ProjectPlanningEvaluation;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/_internal/platform/knowledge/project-planning/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/project-planning/readiness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EAIzB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAiBpB,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,oBAAoB,GAAG,yBAAyB,CA2GvG"}

package/dist/_internal/platform/knowledge/project-planning/readiness.js

@@ -0,0 +1,124 @@
+const VAGUE_TERMS = [
+    'better',
+    'improve',
+    'improved',
+    'setup',
+    'integration',
+    'agent channel',
+    'remote',
+    'thing',
+    'stuff',
+    'etc',
+    'clean up',
+    'fix it',
+];
+export function evaluateProjectPlanningReadiness(state) {
+    const gaps = [];
+    const goal = state.goal.trim();
+    if (!goal) {
+        gaps.push(blockingQuestion('missing-goal', 'The plan needs a concrete goal before it can be executed.', 'What outcome should this plan produce?', 'A clear outcome lets the TUI inspect the right code and ask only relevant follow-up questions.', 'State the user-visible behavior or project change that should exist when the work is done.'));
+    }
+    if (!state.scope?.trim() && state.constraints.length === 0) {
+        gaps.push(blockingQuestion('missing-scope', 'The plan has no explicit boundary for what is included or excluded.', 'What is in scope, and what should be left out for this pass?', 'Scope boundaries prevent the planning loop from turning a focused change into unrelated work.', 'Define the first-pass scope and record do-later items separately.'));
+    }
+    for (const question of state.openQuestions) {
+        if ((question.status ?? 'open') === 'open') {
+            gaps.push({
+                id: `open-question:${question.id}`,
+                kind: 'open-question',
+                severity: 'blocking',
+                message: `Open planning question: ${question.prompt}`,
+                question,
+            });
+        }
+    }
+    const vagueTerm = firstVagueTerm(goal);
+    if (vagueTerm && state.answeredQuestions.length === 0 && state.decisions.length === 0) {
+        gaps.push(blockingQuestion('ambiguous-language', `The goal uses ambiguous language (${JSON.stringify(vagueTerm)}) without recorded clarification.`, `When you say ${JSON.stringify(vagueTerm)}, what concrete behavior should change?`, 'GoodVibes should challenge vague words before work starts so future agents do not implement the wrong thing.', 'Define the term in project language or replace it with concrete expected behavior.'));
+    }
+    if (goal && state.tasks.length === 0) {
+        gaps.push(blockingQuestion('missing-tasks', 'The plan has no decomposed tasks.', 'What are the smallest useful implementation tasks for this goal?', 'Task decomposition is what lets the TUI identify dependencies, parallel agent work, and verification gates.', 'Create task records with likely files, dependencies, and verification notes.'));
+    }
+    if (state.tasks.length > 1 && state.dependencies.length === 0) {
+        gaps.push({
+            id: 'missing-dependencies',
+            kind: 'missing-dependencies',
+            severity: 'advisory',
+            message: 'Multiple tasks exist but no dependency graph has been recorded.',
+        });
+    }
+    const tasksWithoutVerification = state.tasks
+        .filter((task) => (task.verification?.length ?? 0) === 0)
+        .map((task) => task.id);
+    const hasRequiredGate = state.verificationGates.some((gate) => gate.required !== false);
+    if (state.tasks.length > 0 && tasksWithoutVerification.length > 0 && !hasRequiredGate) {
+        gaps.push({
+            id: 'missing-verification',
+            kind: 'missing-verification',
+            severity: 'blocking',
+            message: 'The plan has tasks but no verification gates or per-task verification.',
+            question: {
+                id: 'verification-gates',
+                prompt: 'How should this plan prove that the work is correct?',
+                whyItMatters: 'Verification gates keep execution from ending at code changes that were never checked.',
+                recommendedAnswer: 'Record concrete tests, commands, manual checks, or release gates for the changed behavior.',
+                consequence: 'The plan should not be executable until verification exists.',
+            },
+            relatedTaskIds: tasksWithoutVerification,
+        });
+    }
+    const blocking = gaps.some((gap) => gap.severity === 'blocking');
+    if (!blocking && !state.executionApproved) {
+        gaps.push({
+            id: 'unapproved-execution',
+            kind: 'unapproved-execution',
+            severity: 'blocking',
+            message: 'The plan is structurally ready but has not been approved for execution.',
+            question: {
+                id: 'approve-execution',
+                prompt: 'Is this plan approved for execution?',
+                whyItMatters: 'The TUI owns user approval before local work or agent assignments begin.',
+                recommendedAnswer: 'Approve only after the goal, scope, tasks, dependencies, and verification gates look right.',
+            },
+        });
+    }
+    const readiness = readinessFromGaps(gaps);
+    return {
+        ok: true,
+        projectId: state.projectId,
+        knowledgeSpaceId: state.knowledgeSpaceId,
+        readiness,
+        gaps,
+        ...(gaps[0]?.question ? { nextQuestion: gaps[0].question } : {}),
+        state: {
+            ...state,
+            readiness,
+        },
+    };
+}
+function readinessFromGaps(gaps) {
+    if (gaps.length === 0)
+        return 'executable';
+    if (gaps.some((gap) => gap.severity === 'blocking'))
+        return 'needs-user-input';
+    return 'not-ready';
+}
+function firstVagueTerm(value) {
+    const normalized = value.toLowerCase();
+    return VAGUE_TERMS.find((term) => normalized.includes(term)) ?? null;
+}
+function blockingQuestion(kind, message, prompt, whyItMatters, recommendedAnswer) {
+    const question = {
+        id: kind,
+        prompt,
+        whyItMatters,
+        recommendedAnswer,
+    };
+    return {
+        id: kind,
+        kind,
+        severity: 'blocking',
+        message,
+        question,
+    };
+}

package/dist/_internal/platform/knowledge/project-planning/service.d.ts

@@ -0,0 +1,25 @@
+import { KnowledgeStore } from '../store.js';
+import type { ProjectPlanningDecisionRecordInput, ProjectPlanningDecisionResult, ProjectPlanningDecisionsResult, ProjectPlanningEvaluateInput, ProjectPlanningEvaluation, ProjectPlanningLanguageResult, ProjectPlanningLanguageUpsertInput, ProjectPlanningSpaceInput, ProjectPlanningStateResult, ProjectPlanningStateUpsertInput, ProjectPlanningStatus } from './types.js';
+export interface ProjectPlanningServiceOptions {
+    readonly defaultProjectId?: string;
+}
+export declare class ProjectPlanningService {
+    private readonly store;
+    private readonly defaultProjectId;
+    constructor(store: KnowledgeStore, options?: ProjectPlanningServiceOptions);
+    status(input?: ProjectPlanningSpaceInput): Promise<ProjectPlanningStatus>;
+    getState(input?: ProjectPlanningSpaceInput & {
+        readonly planningId?: string;
+    }): Promise<ProjectPlanningStateResult>;
+    upsertState(input: ProjectPlanningStateUpsertInput): Promise<ProjectPlanningStateResult>;
+    evaluate(input?: ProjectPlanningEvaluateInput): Promise<ProjectPlanningEvaluation>;
+    listDecisions(input?: ProjectPlanningSpaceInput): Promise<ProjectPlanningDecisionsResult>;
+    recordDecision(input: ProjectPlanningDecisionRecordInput): Promise<ProjectPlanningDecisionResult>;
+    getLanguage(input?: ProjectPlanningSpaceInput): Promise<ProjectPlanningLanguageResult>;
+    upsertLanguage(input: ProjectPlanningLanguageUpsertInput): Promise<ProjectPlanningLanguageResult>;
+    private resolveSpace;
+    private sourcesForSpace;
+    private getArtifactSource;
+    private upsertArtifactSource;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/_internal/platform/knowledge/project-planning/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/knowledge/project-planning/service.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAa7C,OAAO,KAAK,EAEV,kCAAkC,EAClC,6BAA6B,EAC7B,8BAA8B,EAC9B,4BAA4B,EAC5B,yBAAyB,EAEzB,6BAA6B,EAC7B,kCAAkC,EAClC,yBAAyB,EAEzB,0BAA0B,EAC1B,+BAA+B,EAC/B,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,qBAAa,sBAAsB;IAI/B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAGvB,KAAK,EAAE,cAAc,EACtC,OAAO,GAAE,6BAAkC;IAKvC,MAAM,CAAC,KAAK,GAAE,yBAA8B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAyB7E,QAAQ,CAAC,KAAK,GAAE,yBAAyB,GAAG;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAevH,WAAW,CAAC,KAAK,EAAE,+BAA+B,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAgBxF,QAAQ,CAAC,KAAK,GAAE,4BAAiC,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAWtF,aAAa,CAAC,KAAK,GAAE,yBAA8B,GAAG,OAAO,CAAC,8BAA8B,CAAC;IAgB7F,cAAc,CAAC,KAAK,EAAE,kCAAkC,GAAG,OAAO,CAAC,6BAA6B,CAAC;IA2BjG,WAAW,CAAC,KAAK,GAAE,yBAA8B,GAAG,OAAO,CAAC,6BAA6B,CAAC;IAc1F,cAAc,CAAC,KAAK,EAAE,kCAAkC,GAAG,OAAO,CAAC,6BAA6B,CAAC;IA2BvG,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,iBAAiB;YASX,oBAAoB;CAyBnC"}