@ai-content-space/loopx 0.1.1 → 0.1.3

package/skills/verify/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: verify
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.

package/src/build-runtime.mjs

@@ -5,6 +5,7 @@ import { runCodexExecJson } from './codex-exec-runtime.mjs';
 
 const DEFAULT_BUILD_MAX_ITERATIONS = 10;
 const DEFAULT_BUILD_LANES = ['execution', 'evidence', 'verification'];
+const DEFAULT_BUILD_CODEX_TIMEOUT_MS = 300000;
 
 function defaultLaneResult(name, iteration) {
   return {
@@ -45,6 +46,56 @@ function normalizeStatus(raw, fallback = 'complete') {
   return fallback;
 }
 
+function normalizeDelegationStatus(raw, fallback = 'pending') {
+  const value = String(raw ?? fallback).trim().toLowerCase();
+  if (['active', 'complete', 'failed', 'blocked', 'pending', 'skipped'].includes(value)) {
+    return value;
+  }
+  return fallback;
+}
+
+function normalizeArray(raw, fallback = []) {
+  return Array.isArray(raw) ? raw.filter((item) => item !== null && item !== undefined).map(String) : fallback;
+}
+
+function normalizeEvidence(raw, fallback = []) {
+  return Array.isArray(raw)
+    ? raw.map((item, index) => ({
+      id: item?.id || `evidence-${index + 1}`,
+      kind: item?.kind || 'artifact',
+      summary: item?.summary || item?.message || 'Evidence item',
+      ref: item?.ref || item?.path || 'n/a',
+    }))
+    : fallback;
+}
+
+function normalizeDelegations(raw) {
+  return Array.isArray(raw)
+    ? raw.map((item, index) => ({
+      id: item?.id || `delegation-${index + 1}`,
+      role: item?.role || 'implementation',
+      status: normalizeDelegationStatus(item?.status, 'pending'),
+      blocking: item?.blocking !== false,
+      scope: Array.isArray(item?.scope) ? item.scope.map(String) : [],
+      evidence_path: item?.evidence_path || item?.evidencePath || null,
+      summary: item?.summary || 'Build delegation entry',
+    }))
+    : [];
+}
+
+function normalizeLaneReport(name, iteration, raw = {}) {
+  const fallback = defaultLaneResult(name, iteration);
+  return {
+    ...fallback,
+    ...raw,
+    name,
+    status: normalizeStatus(raw.status, fallback.status),
+    summary: raw.summary || fallback.summary,
+    evidence: normalizeEvidence(raw.evidence, fallback.evidence),
+    delegations: normalizeDelegations(raw.delegations),
+  };
+}
+
 function buildIterationData({ slug, iteration, noDeslop = false }, scriptEntry = {}) {
   const laneNames = Array.isArray(scriptEntry.lanes) && scriptEntry.lanes.length > 0
     ? scriptEntry.lanes.map((lane) => lane.name)
@@ -84,6 +135,7 @@ function buildIterationData({ slug, iteration, noDeslop = false }, scriptEntry =
       `deslop=${deslopStatus}`,
       `regression=${regressionStatus}`,
     ],
+    delegations: normalizeDelegations(scriptEntry.delegations),
     architectFindings: scriptEntry.architectFindings || (
       architectVerdict === 'approve'
         ? ['Architect gate approved the build iteration.']
@@ -93,42 +145,267 @@ function buildIterationData({ slug, iteration, noDeslop = false }, scriptEntry =
   };
 }
 
+async function runJsonReport(executor, options, fallback) {
+  try {
+    return await executor(options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      ...fallback,
+      error: message,
+      summary: `${fallback.summary || 'Codex execution failed'}: ${message}`,
+      limitations: [
+        ...normalizeArray(fallback.limitations),
+        message,
+      ],
+    };
+  }
+}
+
 export function createDefaultBuildAdapter() {
   return createRealBuildAdapter();
 }
 
-export function createRealBuildAdapter({ model } = {}) {
+export function buildContextPromptLines(context) {
+  return [
+    `workflow: ${context.slug}`,
+    `iteration: ${context.iteration}`,
+    `noDeslop: ${Boolean(context.noDeslop)}`,
+    `planArtifactPath: ${context.planArtifactPath}`,
+    `testSpecArtifactPath: ${context.testSpecArtifactPath}`,
+    `reviewReworkArtifactPath: ${context.reviewReworkArtifactPath || ''}`,
+    `contextManifestStatus: ${context.contextManifestStatus || 'fallback'}`,
+    `contextManifestPath: ${context.contextManifestPath || ''}`,
+    `contextManifestRows: ${JSON.stringify((context.contextManifestRows || []).map((row) => ({
+      kind: row.kind,
+      path: row.path,
+      reason: row.reason,
+      priority: row.priority,
+    })))}`,
+  ];
+}
+
+function lanePrompt(context, laneName) {
+  const laneInstructions = {
+    execution: [
+      'You are the implementation lane. Continue executing the approved plan in the repository.',
+      'If reviewReworkArtifactPath is present, treat that review artifact as the direct implementation-fix contract while keeping the approved plan and test spec as supporting context.',
+      'You are the build owner for critical-path implementation. You may use native Codex subagents for independent sidecar work, but you remain responsible for integrating results.',
+      'If you delegate work, report each active or completed delegation in the delegations array with a stable id, role, status, blocking flag, scope, and evidence_path.',
+      'Do not report final completion while a blocking delegated task remains active, pending, failed, or blocked.',
+      'Real code edits are allowed. Do not stop because approved plan phases remain; keep working until implementation is complete or a real blocker prevents progress.',
+      'Return status "pending" only when approved work remains but cannot be completed in this lane result, and explain the concrete blocker in limitations.',
+    ],
+    evidence: [
+      'You are the evidence lane. Independently inspect the current implementation and collect evidence that the approved plan is or is not satisfied.',
+      'You may use native Codex subagents for independent evidence gathering. If you do, report each delegation in the delegations array.',
+      'Do not edit files. Focus on artifacts, changed files, API surface coverage, and gaps between the plan and the current worktree.',
+      'Do not treat the live workflow state from the build currently in progress, such as current_stage=build, stage_status=blocked, execution_record_status=partial, or pre-existing build_blockers, as evidence that this current iteration is incomplete.',
+      'Use live state only for locating artifacts or confirming context manifest paths; judge this iteration from current code, fresh artifacts, tests, and concrete acceptance gaps.',
+    ],
+    verification: [
+      'You are the verification lane. Independently run or identify the strongest practical verification for the current implementation.',
+      'You may use native Codex subagents for independent verification checks. If you do, report each delegation in the delegations array.',
+      'Do not edit files. Read actual command output when you run tests/builds/checks. Report failed, pending, skipped, or complete accurately.',
+    ],
+  };
+
+  return [
+    `You are acting as the real loopx build ${laneName} lane.`,
+    ...buildContextPromptLines(context),
+    '',
+    ...(laneInstructions[laneName] || []),
+    '',
+    'Return only raw JSON matching this shape:',
+    '{',
+    '  "status": "complete" | "failed" | "pending" | "skipped",',
+    '  "summary": string,',
+    '  "evidence": [{"id": string, "kind": string, "summary": string, "ref": string}],',
+    '  "delegations": [{"id": string, "role": string, "status": "active" | "complete" | "failed" | "blocked" | "pending" | "skipped", "blocking": boolean, "scope": string[], "evidence_path": string | null, "summary": string}],',
+    '  "executionEvidence": string[],',
+    '  "verificationEvidence": string[],',
+    '  "limitations": string[]',
+    '}',
+    'Do not ask questions. Do not wrap JSON in markdown.',
+  ].join('\n');
+}
+
+function architectPrompt(context, lanes) {
+  return [
+    `You are the independent loopx build architect gate for workflow "${context.slug}".`,
+    ...buildContextPromptLines(context),
+    '',
+    'Review the implementation lane plus evidence and verification lane reports.',
+    'Do not edit files. Return only raw JSON matching this shape:',
+    '{',
+    '  "verdict": "approve" | "reject" | "iterate",',
+    '  "findings": string[],',
+    '  "limitations": string[]',
+    '}',
+    '',
+    'Reject or iterate when approved work remains, evidence is thin, verification is not fresh, or architecture risks remain.',
+    'Do not reject or iterate solely because a lane cites the live workflow state from the build currently in progress, such as current_stage=build, stage_status=blocked, execution_record_status=partial, or pre-existing build_blockers.',
+    'Treat that self-referential live-state evidence as stale unless it is tied to a concrete code, artifact, test, or acceptance gap.',
+    'Lane reports:',
+    JSON.stringify(lanes, null, 2),
+  ].join('\n');
+}
+
+function deslopPrompt(context, changedEvidence) {
+  return [
+    `You are the loopx deslop lane for workflow "${context.slug}".`,
+    ...buildContextPromptLines(context),
+    '',
+    'Run a focused cleanup pass on build-owned changes only. Real edits are allowed, but do not widen scope beyond this build iteration.',
+    'Return only raw JSON matching this shape:',
+    '{',
+    '  "status": "complete" | "failed" | "pending" | "skipped",',
+    '  "summary": string,',
+    '  "evidence": [{"id": string, "kind": string, "summary": string, "ref": string}],',
+    '  "limitations": string[]',
+    '}',
+    '',
+    'Build evidence:',
+    JSON.stringify(changedEvidence, null, 2),
+  ].join('\n');
+}
+
+function regressionPrompt(context, deslopReport) {
+  return [
+    `You are the loopx post-deslop regression lane for workflow "${context.slug}".`,
+    ...buildContextPromptLines(context),
+    '',
+    'Run fresh regression verification after the latest implementation/deslop changes. Do not edit files.',
+    'Read actual command output when running verification.',
+    'Return only raw JSON matching this shape:',
+    '{',
+    '  "status": "complete" | "failed" | "pending" | "skipped",',
+    '  "summary": string,',
+    '  "evidence": [{"id": string, "kind": string, "summary": string, "ref": string}],',
+    '  "verificationEvidence": string[],',
+    '  "limitations": string[]',
+    '}',
+    '',
+    'Deslop report:',
+    JSON.stringify(deslopReport, null, 2),
+  ].join('\n');
+}
+
+export function createRealBuildAdapter({ model, codexExecJson = runCodexExecJson } = {}) {
   return {
     maxIterations: DEFAULT_BUILD_MAX_ITERATIONS,
     async executeLanes(context) {
-      const outputPath = join(context.root || context.cwd, 'build-support', `runtime-build-iteration-${context.iteration}.json`);
-      await mkdir(join(context.root || context.cwd, 'build-support'), { recursive: true });
-      const prompt = [
-        `You are acting as the real loopx build runtime for workflow "${context.slug}".`,
-        'Execute the approved build work in this repository and return only raw JSON with this shape:',
-        '{',
-        '  "lanes": [{"name": string, "status": "complete" | "failed" | "pending" | "skipped", "summary": string, "evidence": [{"id": string, "kind": string, "summary": string, "ref": string}]}],',
-        '  "verificationStatus": "complete" | "failed" | "pending" | "skipped",',
-        '  "architectVerdict": "approve" | "reject" | "iterate",',
-        '  "deslopStatus": "complete" | "failed" | "pending" | "skipped",',
-        '  "regressionStatus": "complete" | "failed" | "pending" | "skipped",',
-        '  "executionEvidence": string[],',
-        '  "verificationEvidence": string[],',
-        '  "architectFindings": string[],',
-        '  "limitations": string[]',
-        '}',
-        `noDeslop: ${Boolean(context.noDeslop)}`,
-        `planArtifactPath: ${context.planArtifactPath}`,
-        `testSpecArtifactPath: ${context.testSpecArtifactPath}`,
-        'Do not ask questions. Real code edits are allowed. Keep execution-record.md as the sole canonical execution artifact; return JSON only, no markdown.',
-      ].join('\n');
-      const report = await runCodexExecJson({
+      const supportRoot = join(context.root || context.cwd, 'build-support');
+      await mkdir(supportRoot, { recursive: true });
+      const timeoutMs = Number(process.env.LOOPX_BUILD_CODEX_TIMEOUT_MS || DEFAULT_BUILD_CODEX_TIMEOUT_MS);
+
+      const runLane = async (laneName) => {
+        const raw = await runJsonReport(codexExecJson, {
+          cwd: context.cwd,
+          prompt: lanePrompt(context, laneName),
+          outputPath: join(supportRoot, `runtime-${laneName}-iteration-${context.iteration}.json`),
+          model,
+          timeoutMs,
+        }, {
+          status: 'failed',
+          summary: `${laneName} lane failed`,
+          evidence: [],
+          executionEvidence: [],
+          verificationEvidence: [],
+          limitations: [`${laneName} lane failed before returning structured evidence.`],
+        });
+        return normalizeLaneReport(laneName, context.iteration, raw);
+      };
+
+      const executionLane = await runLane('execution');
+      const [evidenceLane, verificationLane] = await Promise.all([
+        runLane('evidence'),
+        runLane('verification'),
+      ]);
+      const lanes = [executionLane, evidenceLane, verificationLane];
+
+      const architectReport = await runJsonReport(codexExecJson, {
         cwd: context.cwd,
-        prompt,
-        outputPath,
+        prompt: architectPrompt(context, lanes),
+        outputPath: join(supportRoot, `runtime-architect-iteration-${context.iteration}.json`),
         model,
+        timeoutMs,
+      }, {
+        verdict: 'reject',
+        findings: ['Architect gate failed before returning structured evidence.'],
+        limitations: ['Architect gate did not complete.'],
+      });
+
+      const deslopReport = context.noDeslop
+        ? {
+          status: 'skipped',
+          summary: 'Deslop skipped by --no-deslop.',
+          evidence: [],
+          limitations: [],
+        }
+        : await runJsonReport(codexExecJson, {
+          cwd: context.cwd,
+          prompt: deslopPrompt(context, lanes.flatMap((lane) => lane.evidence || [])),
+          outputPath: join(supportRoot, `runtime-deslop-iteration-${context.iteration}.json`),
+          model,
+          timeoutMs,
+        }, {
+          status: 'failed',
+          summary: 'Deslop lane failed before returning structured evidence.',
+          evidence: [],
+          limitations: ['Deslop lane did not complete.'],
+        });
+
+      const regressionReport = context.noDeslop
+        ? {
+          status: 'skipped',
+          summary: 'Regression skipped because --no-deslop skipped deslop.',
+          evidence: [],
+          verificationEvidence: [],
+          limitations: [],
+        }
+        : await runJsonReport(codexExecJson, {
+          cwd: context.cwd,
+          prompt: regressionPrompt(context, deslopReport),
+          outputPath: join(supportRoot, `runtime-regression-iteration-${context.iteration}.json`),
+          model,
+          timeoutMs,
+        }, {
+          status: 'failed',
+          summary: 'Regression lane failed before returning structured evidence.',
+          evidence: [],
+          verificationEvidence: [],
+          limitations: ['Regression lane did not complete.'],
+        });
+
+      return buildIterationData(context, {
+        lanes,
+        verificationStatus: verificationLane.status,
+        architectVerdict: normalizeVerdict(architectReport.verdict, 'reject'),
+        deslopStatus: normalizeStatus(deslopReport.status, context.noDeslop ? 'skipped' : 'failed'),
+        regressionStatus: normalizeStatus(regressionReport.status, context.noDeslop ? 'skipped' : 'failed'),
+        executionEvidence: [
+          ...normalizeArray(executionLane.executionEvidence),
+          ...normalizeArray(evidenceLane.executionEvidence),
+          ...lanes.map((lane) => `${lane.name}:${lane.status}:${lane.summary}`),
+        ],
+        verificationEvidence: [
+          ...normalizeArray(verificationLane.verificationEvidence),
+          ...normalizeArray(regressionReport.verificationEvidence),
+          ...normalizeEvidence(verificationLane.evidence).map((item) => `${item.kind}:${item.summary}:${item.ref}`),
+          ...normalizeEvidence(regressionReport.evidence).map((item) => `${item.kind}:${item.summary}:${item.ref}`),
+        ],
+        architectFindings: normalizeArray(architectReport.findings, ['Architect gate returned no findings.']),
+        delegations: lanes.flatMap((lane) => normalizeDelegations(lane.delegations)),
+        limitations: [
+          ...normalizeArray(executionLane.limitations),
+          ...normalizeArray(evidenceLane.limitations),
+          ...normalizeArray(verificationLane.limitations),
+          ...normalizeArray(architectReport.limitations),
+          ...normalizeArray(deslopReport.limitations),
+          ...normalizeArray(regressionReport.limitations),
+        ],
       });
-      return buildIterationData(context, report);
     },
   };
 }

package/src/build-stop-gate.mjs

@@ -0,0 +1,94 @@
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+const ACTIVE_PHASES = new Set(['starting', 'executing', 'verifying', 'fixing']);
+const READY_PHASES = new Set(['review-ready', 'complete']);
+const TERMINAL_PHASES = new Set(['blocked', 'failed', 'cancelled', 'review-ready', 'complete']);
+
+export function buildActivePath(cwd) {
+  return join(resolve(cwd), '.loopx', 'build-active.json');
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+export async function writeBuildActiveState(cwd, patch) {
+  const path = buildActivePath(cwd);
+  let existing = {};
+  if (existsSync(path)) {
+    try {
+      existing = JSON.parse(await readFile(path, 'utf8'));
+    } catch {
+      existing = {};
+    }
+  }
+  const next = {
+    schema_version: 1,
+    updated_at: nowIso(),
+    ...existing,
+    ...patch,
+  };
+  await writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+export async function readBuildActiveState(cwd) {
+  const path = buildActivePath(cwd);
+  if (!existsSync(path)) {
+    return null;
+  }
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+export function evaluateBuildStopGate(state) {
+  if (!state || state.active !== true) {
+    return {
+      allow: true,
+      reason: 'no_active_build',
+    };
+  }
+
+  if (READY_PHASES.has(state.phase) && state.review_handoff_ready === true) {
+    return {
+      allow: true,
+      reason: 'build_review_handoff_ready',
+      state,
+    };
+  }
+
+  if (TERMINAL_PHASES.has(state.phase) && state.phase !== 'review-ready') {
+    return {
+      allow: true,
+      reason: `build_${state.phase}`,
+      state,
+    };
+  }
+
+  if (ACTIVE_PHASES.has(state.phase) || state.review_handoff_ready !== true) {
+    const blockers = Array.isArray(state.blockers) ? state.blockers.filter(Boolean) : [];
+    const blockerText = blockers.length > 0 ? ` blockers=${blockers.join(',')}` : '';
+    const ownerText = state.build_owner_id ? ` owner: ${state.build_owner_id}.` : '';
+    const delegationCount = Number.isFinite(Number(state.active_delegation_count)) ? Number(state.active_delegation_count) : null;
+    const delegationText = delegationCount !== null ? ` active delegations=${delegationCount}.` : '';
+    const auditText = state.completion_audit_status ? ` completion audit: ${state.completion_audit_status}.` : '';
+    const nextAction = state.next_action ? ` next action: ${state.next_action}` : ' next action: continue the contract-covered next step in $build.';
+    const completionSignal = state.completion_signal ? ` completion signal: ${state.completion_signal}` : ' completion signal: review handoff readiness, a real blocker, user stop, or a return to plan/clarify.';
+    return {
+      allow: false,
+      reason: `loopx build is still active for workflow "${state.slug ?? 'unknown'}" (phase: ${state.phase ?? 'unknown'}; iteration: ${state.iteration ?? 0}/${state.max_iterations ?? '?'}; state: .loopx/build-active.json).${ownerText}${delegationText}${auditText} Do not stop while a contract-covered next step remains.${nextAction}${completionSignal} If the work is genuinely blocked, record the blocker and leave build in a blocked state. If new evidence changes the contract, return to plan/clarify instead of stopping.${blockerText}`,
+      state,
+    };
+  }
+
+  return {
+    allow: true,
+    reason: 'build_state_not_active',
+    state,
+  };
+}
+
+export async function evaluateBuildStopGateForCwd(cwd) {
+  return evaluateBuildStopGate(await readBuildActiveState(cwd));
+}