@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-workflow-loop-contract.mjs

@@ -0,0 +1,259 @@
+import crypto from 'node:crypto';
+import { runtimeWorkflowNextStepGate } from './runtime-workflow-next-step-gate-model.mjs';
+
+const workflowLoopContractStage = 'Stage 104';
+const workflowLoopContractKind = 'workflow-loop-contract';
+const loopPhases = ['plan', 'docs', 'code', 'self_test', 'commit_readiness'];
+
+export function runtimeWorkflowLoopContract({
+  inputIntent = '',
+  normalizedIntent = 'unknown',
+  workflowStart = {},
+  workflowSequence = {},
+  automationReadiness = {},
+  registry = {},
+  registryDigest = '',
+  planFile = '',
+} = {}) {
+  const boundaryAssertions = runtimeWorkflowLoopContractBoundaryAssertions();
+  const phaseContracts = workflowLoopPhaseContracts(normalizedIntent, workflowStart, workflowSequence, planFile);
+  const nextGateSummary = runtimeWorkflowNextStepGate({ normalizedIntent, workflowStart, planFile });
+  const sourceBindings = {
+    workflow_start_stage: workflowStart.stage || '',
+    workflow_start_digest: workflowStart.start_digest || '',
+    workflow_sequence_stage: workflowSequence.stage || '',
+    workflow_sequence_digest: workflowSequence.sequence_digest || '',
+    automation_readiness_stage: automationReadiness.stage || '',
+    automation_readiness_digest: automationReadiness.readiness_digest || '',
+    registry_stage: registry.registry_stage || '',
+    registry_kind: registry.registry_kind || '',
+    registry_version: registry.registry_version || 0,
+    registry_digest: registryDigest,
+    plan_file: planFile || '',
+  };
+  const contract = {
+    version: 1,
+    stage: workflowLoopContractStage,
+    contract_kind: workflowLoopContractKind,
+    input_intent: String(inputIntent || '').trim(),
+    normalized_intent: normalizedIntent || 'unknown',
+    loop_phases: loopPhases,
+    phase_contracts: phaseContracts,
+    source_bindings: sourceBindings,
+    closeout_chain_summary: Array.isArray(registry.closeout_chain)
+      ? registry.closeout_chain.map((item) => ({ order: item.order, command: item.command, purpose: item.purpose }))
+      : [],
+    automation_boundary_summary: automationBoundarySummary(automationReadiness),
+    next_gate_summary: nextGateSummary,
+    next_manual_action: workflowLoopNextManualAction(normalizedIntent, workflowStart, phaseContracts),
+    allowed_followup: ['Stage 105 plan-to-action manifest', 'Stage 106 self-test gate profile', 'Stage 107 commit readiness envelope'],
+    forbidden_actions: [
+      'automation --plan creation from Stage 104',
+      'classified command execution',
+      'test/check/repair execution',
+      'sidecar or .vibecoding-state write',
+      'business source mutation',
+      'git commit/push/PR/merge/tag',
+      'platform API, external network, model, MCP, or subagent invocation',
+    ],
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeWorkflowLoopContractInvariants(contract);
+  return {
+    ...contract,
+    loop_contract_invariants: invariants,
+    manual_action: invariants.pass
+      ? 'Workflow loop contract is ready. Use it as a visible local contract for plan, docs, code, self-test, and commit-readiness; do not execute or commit from Stage 104.'
+      : 'Fix the listed workflow loop contract gaps before using this contract for later planning stages.',
+  };
+}
+
+export function runtimeWorkflowLoopContractInvariants(contract) {
+  const phaseSet = new Set(contract.loop_phases || []);
+  const contractPhaseSet = new Set((contract.phase_contracts || []).map((item) => item.phase));
+  const missingPhases = loopPhases.filter((phase) => !phaseSet.has(phase) || !contractPhaseSet.has(phase));
+  const duplicatePhaseContracts = (contract.phase_contracts || [])
+    .map((item) => item.phase)
+    .filter((item, index, items) => items.indexOf(item) !== index);
+  const incompletePhaseContracts = (contract.phase_contracts || [])
+    .filter((item) => !Array.isArray(item.entry_criteria) || item.entry_criteria.length === 0
+      || !Array.isArray(item.required_evidence) || item.required_evidence.length === 0
+      || !item.recommended_skill_or_command
+      || !item.exit_receipt
+      || !Array.isArray(item.stop_conditions) || item.stop_conditions.length === 0)
+    .map((item) => item.phase || 'unknown');
+  const missingSourceBindings = ['workflow_start_digest', 'workflow_sequence_digest', 'automation_readiness_digest', 'registry_digest']
+    .filter((key) => !contract.source_bindings?.[key]);
+  const writableBoundaries = Object.entries(contract.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const forbiddenMissing = ['git', 'push', 'pr', 'merge', 'platform_api', 'external_network', 'model_invocation', 'subagent', 'mcp', 'business_source_write']
+    .filter((key) => contract.boundary_assertions?.[key] !== false);
+  const executionLeak = (contract.allowed_followup || [])
+    .filter((item) => /execute|\brun\b|git commit|push|merge|\bpr\b|automation --plan/i.test(item));
+  const nextGate = contract.next_gate_summary || {};
+  const nextGateBoundaryLeaks = Object.entries(nextGate.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+
+  const findings = [
+    ...missingPhases.map((item) => `missing loop phase contract: ${item}`),
+    ...duplicatePhaseContracts.map((item) => `duplicate loop phase contract: ${item}`),
+    ...incompletePhaseContracts.map((item) => `incomplete phase contract: ${item}`),
+    ...missingSourceBindings.map((item) => `missing source binding: ${item}`),
+    ...writableBoundaries.map((item) => `boundary assertion must remain false: ${item}`),
+    ...forbiddenMissing.map((item) => `forbidden boundary missing or not false: ${item}`),
+    ...executionLeak.map((item) => `allowed followup must not grant execution: ${item}`),
+    ...(nextGate.gate_kind === 'workflow-next-step-gate' ? [] : ['next_gate_summary.gate_kind is required']),
+    ...(nextGate.current_gate && nextGate.next_gate ? [] : ['next_gate_summary must include current_gate and next_gate']),
+    ...(Array.isArray(nextGate.required_evidence) && nextGate.required_evidence.length > 0 ? [] : ['next_gate_summary.required_evidence is required']),
+    ...(Array.isArray(nextGate.blocked_actions) && nextGate.blocked_actions.length > 0 ? [] : ['next_gate_summary.blocked_actions is required']),
+    ...nextGateBoundaryLeaks.map((item) => `next gate boundary assertion must remain false: ${item}`),
+  ];
+
+  return {
+    pass: findings.length === 0,
+    checked: [
+      'five_phase_loop_coverage',
+      'phase_contract_completeness',
+      'source_digest_bindings',
+      'read_only_boundary_assertions',
+      'no_execution_followup',
+      'next_step_gate_summary',
+    ],
+    findings,
+  };
+}
+
+export function runtimeWorkflowLoopContractBoundaryAssertions() {
+  return {
+    workflow_loop_contract_artifact: false,
+    automation_plan_artifact: false,
+    one_shot_execution_artifact: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    command_execution: false,
+    runtime_action: false,
+    workflow_execution: false,
+    verification_execution: false,
+    test_execution: false,
+    repair_execution: false,
+    scheduler: false,
+    daemon: false,
+    retry: false,
+    git: false,
+    git_write: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    worktree: false,
+    business_source_write: false,
+    source_merge: false,
+  };
+}
+
+export function runtimeWorkflowLoopContractDigestPayload(contract) {
+  return {
+    stage: contract.stage,
+    contract_kind: contract.contract_kind,
+    input_intent: contract.input_intent,
+    normalized_intent: contract.normalized_intent,
+    loop_phases: contract.loop_phases,
+    phase_contracts: contract.phase_contracts,
+    source_bindings: contract.source_bindings,
+    closeout_chain_summary: contract.closeout_chain_summary,
+    automation_boundary_summary: contract.automation_boundary_summary,
+    next_gate_summary: contract.next_gate_summary,
+    next_manual_action: contract.next_manual_action,
+    allowed_followup: contract.allowed_followup,
+    forbidden_actions: contract.forbidden_actions,
+    boundary_assertions: contract.boundary_assertions,
+    loop_contract_invariants: contract.loop_contract_invariants,
+  };
+}
+
+export function digestWorkflowLoopContract(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function workflowLoopPhaseContracts(intent, workflowStart, workflowSequence, planFile) {
+  const firstSkill = workflowStart.cockpit_summary?.recommended_next_skill || workflowSequence.route_summary?.first_skill || 'using-vibecoding';
+  return [
+    {
+      phase: 'plan',
+      entry_criteria: planFile ? ['accepted local plan file is provided', 'plan scope and acceptance are explicit'] : ['goal, scope, constraints, and acceptance are explicit', 'workflow entry has been selected'],
+      required_evidence: planFile ? [`plan lint evidence for ${planFile}`] : ['visible workflow start receipt', 'selected planning or implementation workflow'],
+      recommended_skill_or_command: planFile ? 'planner --lint --from-file <local-plan-file> --json' : firstSkill,
+      exit_receipt: 'accepted plan or explicit lightweight-scope decision',
+      stop_conditions: ['unclear acceptance', 'missing plan for non-trivial implementation', 'request to execute without workflow entry'],
+    },
+    {
+      phase: 'docs',
+      entry_criteria: ['plan phase has identified externally visible behavior or runtime contract changes'],
+      required_evidence: ['docs or marker expectations are named when behavior/contract changes', 'no documentation claim without corresponding implementation/check marker'],
+      recommended_skill_or_command: 'update scoped README/roadmap/check markers only when contract changes require it',
+      exit_receipt: 'documentation sync evidence or explicit docs-not-needed reason',
+      stop_conditions: ['contract change without doc/check marker plan', 'docs-only claim that changes runtime behavior'],
+    },
+    {
+      phase: 'code',
+      entry_criteria: ['plan/docs expectations are bounded', 'verification strategy is known before editing'],
+      required_evidence: ['changed file scope', 'task-level acceptance target', 'no unrelated working tree rewrite'],
+      recommended_skill_or_command: intent === 'debug' ? 'vibe-systematic-debugging -> vibe-implementation' : 'vibe-test-driven-development -> vibe-implementation',
+      exit_receipt: 'bounded implementation diff with task-level acceptance notes',
+      stop_conditions: ['root cause unknown for bug work', 'source mutation outside accepted scope', 'subagent/platform/git action requested without explicit permission'],
+    },
+    {
+      phase: 'self_test',
+      entry_criteria: ['code/docs diff is bounded', 'relevant check surface is known'],
+      required_evidence: ['syntax/check output or manual verification evidence', 'known unverified items are recorded'],
+      recommended_skill_or_command: 'vibe-verification-before-completion plus targeted runtime/release checks',
+      exit_receipt: 'fresh self-test evidence or blocked verification reason',
+      stop_conditions: ['missing fresh verification evidence', 'failed check without root-cause follow-up', 'unbounded broad test request that writes outside sandbox'],
+    },
+    {
+      phase: 'commit_readiness',
+      entry_criteria: ['self-test evidence exists', 'completion evidence is ready', 'user explicitly requests commit readiness or commit'],
+      required_evidence: ['completion evidence bundle', 'commit subject guard', 'status/stat review', 'explicit no-push boundary'],
+      recommended_skill_or_command: 'completion --evidence-bundle -> release --commit-guard -> manual confirmation',
+      exit_receipt: 'commit readiness decision; no commit unless explicitly confirmed',
+      stop_conditions: ['uncommitted unrelated changes not understood', 'commit subject guard blocked', 'push/PR/merge requested without explicit authorization'],
+    },
+  ];
+}
+
+function automationBoundarySummary(automationReadiness) {
+  return {
+    readiness_kind: automationReadiness.readiness_kind || '',
+    category_counts: automationReadiness.category_counts || {},
+    auto_safe_is_execution: false,
+    confirm_required_needs_user_confirmation: true,
+    advice_only_is_not_execution_approval: true,
+    forbidden_is_permanent_boundary: true,
+  };
+}
+
+function workflowLoopNextManualAction(intent, workflowStart, phaseContracts) {
+  const blocked = workflowStart.blocked_reasons || [];
+  if (blocked.length > 0) return `Resolve workflow start blockers before entering the loop: ${blocked.slice(0, 3).join('; ')}`;
+  const first = phaseContracts[0];
+  return `Enter the ${first.phase} phase for ${intent || 'unknown'} and preserve its exit receipt before moving to docs/code/self_test/commit_readiness.`;
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}

package/tools/vibe-runtime/runtime-workflow-next-step-gate-model.mjs

@@ -0,0 +1,106 @@
+const GATE_ORDER = Object.freeze(['entry', 'plan', 'docs', 'code', 'self_test', 'review_closeout']);
+
+const GATE_EVIDENCE = Object.freeze({
+  entry: Object.freeze(['visible workflow start receipt', 'profile boundary summary', 'selected route or clarification decision']),
+  plan: Object.freeze(['goal, scope, and acceptance', 'bounded file/task plan', 'verification strategy before implementation']),
+  docs: Object.freeze(['contract or docs sync decision', 'marker expectations when behavior changes']),
+  code: Object.freeze(['accepted plan evidence', 'allowed file scope', 'task-level acceptance target']),
+  self_test: Object.freeze(['fresh syntax/check/manual verification evidence', 'known unverified items']),
+  review_closeout: Object.freeze(['review decision or explicit no-review reason', 'completion evidence summary']),
+});
+
+const BLOCKED_ACTIONS = Object.freeze({
+  entry: Object.freeze(['source write', 'workflow execution', 'subagent', 'git or platform action']),
+  plan: Object.freeze(['code gate', 'self-test gate', 'closeout claim']),
+  docs: Object.freeze(['contract claim without docs/check sync decision']),
+  code: Object.freeze(['out-of-scope source write', 'subagent or platform action without permission']),
+  self_test: Object.freeze(['completion claim', 'commit readiness']),
+  review_closeout: Object.freeze(['commit, push, PR, or merge without explicit request']),
+});
+
+export function runtimeWorkflowNextStepGate({
+  normalizedIntent = 'unknown',
+  workflowStart = {},
+  planFile = '',
+} = {}) {
+  const startBlockers = workflowStart.blocked_reasons || [];
+  if (startBlockers.length > 0) {
+    return gateSummary({
+      normalizedIntent,
+      currentGate: 'entry',
+      pass: false,
+      nextGate: 'entry',
+      requiredEvidence: GATE_EVIDENCE.entry,
+      blockedActions: BLOCKED_ACTIONS.entry,
+      reasons: startBlockers.slice(0, 5),
+    });
+  }
+
+  if (!planFile) {
+    return gateSummary({
+      normalizedIntent,
+      currentGate: 'plan',
+      pass: false,
+      nextGate: 'plan',
+      requiredEvidence: GATE_EVIDENCE.plan,
+      blockedActions: BLOCKED_ACTIONS.plan,
+      reasons: ['local plan evidence is not provided; code gate remains blocked'],
+    });
+  }
+
+  return gateSummary({
+    normalizedIntent,
+    currentGate: 'docs',
+    pass: true,
+    nextGate: 'docs',
+    requiredEvidence: GATE_EVIDENCE.docs,
+    blockedActions: BLOCKED_ACTIONS.docs,
+    reasons: ['plan evidence is named; decide docs/check sync before code gate'],
+  });
+}
+
+export function runtimeWorkflowNextStepGateBoundaryAssertions() {
+  return {
+    writes: false,
+    state_directory_created: false,
+    next_gate_artifact: false,
+    sidecar_write: false,
+    source_write: false,
+    workflow_execution: false,
+    skill_execution: false,
+    command_execution: false,
+    test_execution: false,
+    check_execution: false,
+    runtime_action: false,
+    auto_execution: false,
+    git: false,
+    git_write: false,
+    pr: false,
+    push: false,
+    merge: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    business_source_write: false,
+  };
+}
+
+function gateSummary({ normalizedIntent, currentGate, pass, nextGate, requiredEvidence, blockedActions, reasons }) {
+  return {
+    gate_kind: 'workflow-next-step-gate',
+    normalized_intent: normalizedIntent || 'unknown',
+    gate_order: GATE_ORDER,
+    current_gate: currentGate,
+    pass,
+    next_gate: nextGate,
+    required_evidence: [...requiredEvidence],
+    blocked_actions: [...blockedActions],
+    reasons: [...reasons],
+    boundary_assertions: runtimeWorkflowNextStepGateBoundaryAssertions(),
+    writes: false,
+    local_only: true,
+    deterministic: true,
+  };
+}