codex-genesis-harness 0.1.8 → 0.1.9

package/scripts/validation_gates.sh

@@ -1,85 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-echo "====================================="
-echo "   RUNNING VALIDATION GATES          "
-echo "====================================="
-
 repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-FAILURES=0
-
-fail() {
-  echo "❌ VALIDATION FAILED: $*" >&2
-  FAILURES=$((FAILURES + 1))
-}
-
-echo "1. Checking for leftover debug logs and TODOs..."
-# Exclude node_modules, .git, .codex, scripts, .codebase, bin, and md files
-EXCLUDES="--exclude-dir=node_modules --exclude-dir=.git --exclude-dir=.codex --exclude-dir=scripts --exclude-dir=.codebase --exclude-dir=bin --exclude=*.md"
-
-# We check for TODO, FIXME, console.log, print( (python)
-# Using grep recursively
-if grep -rn $EXCLUDES -E 'TODO|FIXME|console\.log|print\(' "$repo_root" | grep -v 'validation_gates.sh'; then
-  fail "Found unresolved TODOs or leftover debug logs in codebase!"
-else
-  echo "✅ Codebase cleanliness gate passed."
-fi
-
-echo "2. Verifying Harness Integrity..."
-if [ -f "$repo_root/scripts/verify.sh" ]; then
-  if bash "$repo_root/scripts/verify.sh" > /dev/null 2>&1; then
-    echo "✅ Harness Integrity gate passed."
-  else
-    fail "verify.sh failed. Core files or templates are missing."
-  fi
-fi
-
-echo "3. Checking for Documentation Drift (Alignment with Code changes)..."
-if [ -d "$repo_root/.git" ]; then
-  # Get list of modified files in git
-  CHANGED_FILES=$(git diff --name-only HEAD 2>/dev/null || true)
-  
-  if [ -n "$CHANGED_FILES" ]; then
-    # API Drift: code under src/ modified, but API contracts not updated
-    if echo "$CHANGED_FILES" | grep -qE "src/.*api|src/.*endpoint|src/.*route" && ! echo "$CHANGED_FILES" | grep -qE "contracts/api/|.codebase/API_CONTRACTS.md|.planning/API_DOCS.md"; then
-      echo "⚠️  WARNING: You changed API code under src/ but did not update API_CONTRACTS.md, API_DOCS.md or contracts/api/!"
-    fi
-
-    # Database Drift: models or schemas modified, but DOMAIN_MODELS.md not updated
-    if echo "$CHANGED_FILES" | grep -qE "model|schema|db" && ! echo "$CHANGED_FILES" | grep -qE ".codebase/DOMAIN_MODELS.md"; then
-      echo "⚠️  WARNING: You changed database/model files but did not update DOMAIN_MODELS.md!"
-    fi
-
-    # Test Drift: test files modified, but TEST_MATRIX.md not updated
-    if echo "$CHANGED_FILES" | grep -qE "tests/|playwright/" && ! echo "$CHANGED_FILES" | grep -qE ".codebase/TEST_MATRIX.md"; then
-      echo "⚠️  WARNING: You changed test files but did not update TEST_MATRIX.md!"
-    fi
-
-    # Dependency Drift: package.json dependencies modified, but DEPENDENCY_GRAPH.md not updated
-    if echo "$CHANGED_FILES" | grep -q "package.json" && ! echo "$CHANGED_FILES" | grep -q ".codebase/DEPENDENCY_GRAPH.md"; then
-      if git diff package.json 2>/dev/null | grep -qE '^\+.*"(dependencies|devDependencies)"'; then
-        echo "⚠️  WARNING: You updated package.json dependencies but did not update DEPENDENCY_GRAPH.md!"
-      fi
-    fi
-    echo "✅ Documentation alignment check complete."
-  fi
-else
-  echo "⚠️  Git repository not found. Skipping drift check."
-fi
-
-echo "4. Running Pre-emptive Prompt Sentinel check..."
-if [ -f "$repo_root/scripts/prompt_sentinel.js" ] && [ -f "$repo_root/.codebase/CURRENT_STATE.md" ]; then
-  # Run prompt sentinel check on the state file as a pre-flight test
-  node "$repo_root/scripts/prompt_sentinel.js" --check "$repo_root/.codebase/CURRENT_STATE.md" --threshold 1500
-fi
-
-
 
-echo "====================================="
-if [ $FAILURES -gt 0 ]; then
-  echo "❌ $FAILURES Validation Gate(s) failed."
-  exit 1
-else
-  echo "✅ All Validation Gates passed! Output is ready for production."
-  exit 0
-fi
+echo "Running canonical Genesis verification gate..."
+exec node "$repo_root/bin/genesis-harness.js" verify-gate

package/scripts/verify.sh

@@ -55,7 +55,7 @@ required_context_files=(
 )
 
 required_contract_roots=(api agents events ui)
-required_fixture_roots=(api agents pipeline render tts images videos)
+required_fixture_roots=(api agents pipeline render images)
 required_test_roots=(contracts integration unit fixtures)
 required_playwright_roots=(e2e smoke visual fixtures)
 required_observability_roots=(agent-runs failures decision-logs)
@@ -180,6 +180,8 @@ verify_repository_harness() {
 
 verify_repository_harness
 
+node "$repo_root/scripts/check-repository-hygiene.js"
+
 verify_skill_metadata() {
   local skill_dir="$1"
   local expected_name="$2"

package/tests/fixtures/fixture-index.md

@@ -2,3 +2,8 @@
 
 Map every fixture to the contract, test, and module it validates.
 
+| Fixture | Validates | Test / Module |
+|---|---|---|
+| `fixtures/pipeline/run-to-feature-execution-fixture.md` | `run --idea` advances from discovery into active feature execution with resumable artifacts plus typed API/UI contract scaffolding | `tests/integration/cli-smoke.test.js`, `bin/genesis-harness.js` |
+| `fixtures/pipeline/feature-completion-fixture.md` | `next` and `complete-feature` close an active feature only after executable verification and explicit evidence | `tests/integration/cli-smoke.test.js`, `bin/genesis-harness.js` |
+| `fixtures/pipeline/end-to-end-project-lifecycle-fixture.md` | Multi-feature promotion, project-wide verification, release-ready handoff, idempotent completion, event history, and pipeline audit | `tests/integration/cli-smoke.test.js`, `bin/genesis-harness.js` |

package/tests/integration/cli-smoke.test.js

@@ -24,6 +24,15 @@ function run(args, cwd = tmp) {
   });
 }
 
+function runFailure(args, cwd = tmp) {
+  try {
+    run(args, cwd);
+  } catch (error) {
+    return `${error.stdout || ""}${error.stderr || ""}`;
+  }
+  assert.fail(`expected command to fail: ${args.join(" ")}`);
+}
+
 function runPostinstall(initCwd) {
   return execFileSync(process.execPath, [cli, "postinstall"], {
     cwd: repoRoot,
@@ -69,6 +78,400 @@ assert(
 const pathOutput = run(["path"]);
 assert(pathOutput.includes("genesis-harness"), "path should include installed skill paths");
 
+const initTmp = fs.mkdtempSync(path.join(os.tmpdir(), "genesis-init-smoke-"));
+fs.writeFileSync(path.join(initTmp, "README.md"), "# Blank project\n");
+const initOutput = run(["init", "--platform", "codex", "--yes"], initTmp);
+assert(initOutput.includes("Initialization Complete"), "init should complete non-interactively");
+assert(
+  fs.existsSync(path.join(initTmp, ".planning", "STATE.md")),
+  "init should create planning state for empty projects"
+);
+assert(
+  fs.existsSync(path.join(initTmp, ".codex", "skills", "genesis-harness", "SKILL.md")),
+  "codex init should install packaged skills into the project-local .codex/skills directory"
+);
+assert(
+  !fs.existsSync(path.join(initTmp, "codex-home", "skills", "genesis-harness")),
+  "codex init should not write packaged skills into CODEX_HOME"
+);
+assert(
+  !fs.existsSync(path.join(initTmp, "agents-home", "skills", "genesis-harness")),
+  "codex init should not write packaged skills into GENESIS_HARNESS_HOME"
+);
+assert(
+  fs.existsSync(path.join(initTmp, ".planning", "phases", "01-discovery-and-qa", "TASKS.md")),
+  "init should create a post-foundation discovery phase"
+);
+assert(
+  fs.existsSync(path.join(initTmp, ".codebase", "PHASE_DEPENDENCY_MAP.md")),
+  "init should create a phase dependency map"
+);
+const initState = fs.readFileSync(path.join(initTmp, ".planning", "STATE.md"), "utf8");
+assert(
+  initState.includes("Run discovery Q&A to confirm product approach and tech stack."),
+  "init should route the next step to discovery Q&A"
+);
+const qaBrief = fs.readFileSync(path.join(initTmp, ".planning", "INIT_QA.md"), "utf8");
+assert(qaBrief.includes("tech stack"), "init should seed tech stack QA prompts");
+assert(qaBrief.includes("QA sign-off"), "init should seed QA approval prompts");
+const roadmap = fs.readFileSync(path.join(initTmp, ".planning", "ROADMAP.md"), "utf8");
+assert(roadmap.includes("01 Discovery & QA"), "init should add a discovery phase to the roadmap");
+
+const ideaTmp = fs.mkdtempSync(path.join(os.tmpdir(), "genesis-init-idea-"));
+const idea =
+  "Build a lightweight meal-planning app for busy families that suggests weekly menus, tracks groceries, and works on mobile first.";
+const ideaInitOutput = run(["init", "--platform", "codex", "--yes", "--idea", idea], ideaTmp);
+assert(ideaInitOutput.includes("Initialization Complete"), "init with idea should complete");
+const projectDoc = fs.readFileSync(path.join(ideaTmp, ".planning", "PROJECT.md"), "utf8");
+assert(projectDoc.includes("meal-planning app"), "init with idea should seed project summary from the idea");
+const requirementsDoc = fs.readFileSync(path.join(ideaTmp, ".planning", "REQUIREMENTS.md"), "utf8");
+assert(requirementsDoc.includes("weekly menus"), "init with idea should seed functional requirements from the idea");
+const stackDoc = fs.readFileSync(path.join(ideaTmp, ".planning", "STACK.md"), "utf8");
+assert(stackDoc.includes("Mobile-first"), "init with idea should capture stack clues from the idea");
+const summaryDoc = fs.readFileSync(path.join(ideaTmp, ".planning", "SUMMARY.md"), "utf8");
+assert(summaryDoc.includes("meal-planning app"), "init with idea should carry the idea into the planning summary");
+const initQaDoc = fs.readFileSync(path.join(ideaTmp, ".planning", "INIT_QA.md"), "utf8");
+assert(initQaDoc.includes(idea), "init with idea should embed the original user brief for QA follow-up");
+
+const runTmp = fs.mkdtempSync(path.join(os.tmpdir(), "genesis-run-idea-"));
+const runIdea =
+  "Create a concierge booking assistant for boutique hotels that helps staff manage guest requests from a tablet.";
+const runOutput = run(
+  [
+    "run",
+    "--platform",
+    "codex",
+    "--yes",
+    "--idea",
+    runIdea,
+    "--product-approach",
+    "Start with a staff-facing web dashboard optimized for tablet use in the lobby.",
+    "--primary-user",
+    "Front-desk hotel staff",
+    "--v1-outcome",
+    "Staff can log, prioritize, and resolve guest requests in one queue.",
+    "--qa-owner",
+    "Operations lead",
+    "--backend",
+    "Node.js",
+    "--frontend",
+    "React",
+    "--database",
+    "PostgreSQL",
+    "--deployment",
+    "Fly.io",
+    "--test-strategy",
+    "Node integration tests and Playwright smoke tests",
+    "--stack-owner",
+    "Tech lead"
+  ],
+  runTmp
+);
+assert(runOutput.includes("Run pipeline complete"), "run should complete the bootstrap pipeline");
+const runProjectDoc = fs.readFileSync(path.join(runTmp, ".planning", "PROJECT.md"), "utf8");
+assert(runProjectDoc.includes("Front-desk hotel staff"), "run should record the primary user");
+assert(runProjectDoc.includes("staff-facing web dashboard"), "run should record the chosen product approach");
+const runStackDoc = fs.readFileSync(path.join(runTmp, ".planning", "STACK.md"), "utf8");
+assert(runStackDoc.includes("Language: Node.js"), "run should fill backend stack details");
+assert(runStackDoc.includes("Framework: React"), "run should fill frontend stack details");
+const runAdrDoc = fs.readFileSync(path.join(runTmp, ".planning", "decisions", "ADR-001-tech-stack.md"), "utf8");
+assert(runAdrDoc.includes("Status: Accepted"), "run should close the tech-stack ADR when answers are provided");
+const runInitQaDoc = fs.readFileSync(path.join(runTmp, ".planning", "INIT_QA.md"), "utf8");
+assert(runInitQaDoc.includes("Operations lead"), "run should record the QA owner");
+assert(runInitQaDoc.includes("Fly.io"), "run should record deployment direction");
+const runRequirementsDoc = fs.readFileSync(path.join(runTmp, ".planning", "REQUIREMENTS.md"), "utf8");
+assert(
+  !runRequirementsDoc.includes("guest requests are handled without context loss"),
+  "run should not hard-code a hotel-specific user-story outcome into generic planning docs"
+);
+assert(
+  runRequirementsDoc.includes("the core workflow can be completed without context loss"),
+  "run should use a generic user-story outcome in seeded planning docs"
+);
+const runState = JSON.parse(fs.readFileSync(path.join(runTmp, ".codebase", "state.json"), "utf8"));
+assert.strictEqual(runState.current_state, "IMPLEMENTATION", "run should advance the bootstrap state into feature execution");
+assert(
+  runState.pending_tasks.includes("Implement the first feature slice"),
+  "run should queue the first implementation slice"
+);
+assert(runState.active_feature, "run should record the active feature path");
+const activeFeatureDir = path.join(runTmp, runState.active_feature);
+assert(fs.existsSync(activeFeatureDir), "run should scaffold the active feature directory");
+assert(
+  fs.existsSync(path.join(activeFeatureDir, "SPEC.md")),
+  "run should create a feature specification before implementation"
+);
+assert(
+  fs.existsSync(path.join(activeFeatureDir, "PLAN.md")),
+  "run should create a feature plan before implementation"
+);
+assert(
+  fs.existsSync(path.join(activeFeatureDir, "TEST_CONTRACT.md")),
+  "run should create a feature test contract before implementation"
+);
+assert(
+  fs.existsSync(path.join(activeFeatureDir, "VERIFICATION.md")),
+  "run should create feature verification instructions before implementation"
+);
+const activeFeatureSpec = fs.readFileSync(path.join(activeFeatureDir, "SPEC.md"), "utf8");
+assert(activeFeatureSpec.includes("Front-desk hotel staff"), "run should seed the feature spec with the primary user");
+assert(activeFeatureSpec.includes("one queue"), "run should seed the feature spec with the v1 outcome");
+const activeFeaturePlan = fs.readFileSync(path.join(activeFeatureDir, "PLAN.md"), "utf8");
+assert(activeFeaturePlan.includes("scripts/verify.sh"), "run should seed implementation verification commands");
+const activeFeatureContract = fs.readFileSync(path.join(activeFeatureDir, "TEST_CONTRACT.md"), "utf8");
+assert(activeFeatureContract.includes("contracts/ui/"), "run should link the feature test contract to generated UI contracts");
+assert(activeFeatureContract.includes("contracts/api/"), "run should link the feature test contract to generated API contracts");
+const featureIndex = fs.readFileSync(path.join(runTmp, ".planning", "FEATURE_INDEX.md"), "utf8");
+assert(featureIndex.includes(path.basename(activeFeatureDir)), "run should register the active feature in FEATURE_INDEX.md");
+const generatedUiContractPath = path.join(runTmp, "contracts", "ui", path.basename(activeFeatureDir), "screen-contract.json");
+assert(fs.existsSync(generatedUiContractPath), "run should scaffold a UI contract for a UI-capable first feature");
+const generatedUiContract = JSON.parse(fs.readFileSync(generatedUiContractPath, "utf8"));
+assert(generatedUiContract.contract_id.startsWith("UI-"), "run should generate a typed UI contract id");
+assert.strictEqual(generatedUiContract.inputs.route, "/staff-queue", "run should derive a UI route for the first feature");
+assert(
+  generatedUiContract.outputs.events.some(event => event.name === "onQueueItemSelect"),
+  "run should generate UI events tailored to the first feature"
+);
+const generatedUiFixturePath = path.join(runTmp, "playwright", "fixtures", `${path.basename(activeFeatureDir)}-ui-fixture.md`);
+assert(fs.existsSync(generatedUiFixturePath), "run should scaffold a UI fixture for a UI-capable first feature");
+const generatedUiFixture = fs.readFileSync(generatedUiFixturePath, "utf8");
+assert(generatedUiFixture.includes("/staff-queue"), "run should seed the UI fixture with the derived route");
+const generatedApiContractDir = path.join(runTmp, "contracts", "api", path.basename(activeFeatureDir));
+assert(fs.existsSync(path.join(generatedApiContractDir, "request.json")), "run should scaffold an API request contract for a backend-capable first feature");
+assert(fs.existsSync(path.join(generatedApiContractDir, "response.json")), "run should scaffold an API response contract for a backend-capable first feature");
+const generatedApiRequest = JSON.parse(fs.readFileSync(path.join(generatedApiContractDir, "request.json"), "utf8"));
+assert.strictEqual(generatedApiRequest.method, "POST", "run should generate an API method for the first feature");
+assert.strictEqual(generatedApiRequest.path, "/api/staff-queue/items", "run should derive an API path for the first feature");
+const generatedApiResponse = JSON.parse(fs.readFileSync(path.join(generatedApiContractDir, "response.json"), "utf8"));
+assert.strictEqual(generatedApiResponse.status, 200, "run should generate an expected successful API status");
+assert.strictEqual(generatedApiResponse.body.status, "queued", "run should tailor the API response body to the first feature");
+const generatedApiFixturePath = path.join(runTmp, "fixtures", "api", `${path.basename(activeFeatureDir)}-api-fixture.md`);
+assert(fs.existsSync(generatedApiFixturePath), "run should scaffold an API fixture for a backend-capable first feature");
+const generatedApiFixture = fs.readFileSync(generatedApiFixturePath, "utf8");
+assert(generatedApiFixture.includes("/api/staff-queue/items"), "run should seed the API fixture with the derived endpoint");
+const runArtifactDir = path.join(runTmp, ".runs", runState.session_id);
+assert(
+  fs.existsSync(path.join(runArtifactDir, "STATE.json")),
+  "run should persist a resumable state artifact for the active session"
+);
+const runArtifactState = JSON.parse(fs.readFileSync(path.join(runArtifactDir, "STATE.json"), "utf8"));
+assert.strictEqual(
+  runArtifactState.current_state,
+  "IMPLEMENTATION",
+  "run artifact state should mirror the active implementation phase"
+);
+assert(
+  fs.existsSync(path.join(runArtifactDir, "DISCOVERY.json")),
+  "run should persist discovery answers for later resume"
+);
+assert(
+  fs.existsSync(path.join(runArtifactDir, "RESUME.md")),
+  "run should persist a human-readable resume brief"
+);
+const resumeOutput = run(["resume"], runTmp);
+assert(resumeOutput.includes("Resume session:"), "resume should print the active session summary");
+assert(resumeOutput.includes(runState.session_id), "resume should reference the active session id");
+assert(resumeOutput.includes("IMPLEMENTATION"), "resume should show the current execution state");
+assert(
+  resumeOutput.includes(path.basename(activeFeatureDir)),
+  "resume should reference the active feature directory"
+);
+assert(
+  resumeOutput.includes("Implement the first feature slice"),
+  "resume should direct the next implementation task"
+);
+const featureRegistryPath = path.join(runTmp, ".planning", "FEATURE_REGISTRY.json");
+assert(
+  fs.existsSync(featureRegistryPath),
+  "run should create a machine-readable project feature registry"
+);
+const projectFeatureRegistry = JSON.parse(fs.readFileSync(featureRegistryPath, "utf8"));
+assert.strictEqual(projectFeatureRegistry.features.length, 1, "run should register the first feature");
+assert.strictEqual(
+  projectFeatureRegistry.features[0].status,
+  "in-progress",
+  "the scaffolded first feature should enter the execution queue"
+);
+assert.strictEqual(
+  projectFeatureRegistry.project_status,
+  "implementation",
+  "the project registry should record the implementation lifecycle stage"
+);
+
+const secondFeatureTitle = "Notify staff when a guest request changes";
+const addFeatureOutput = run(
+  [
+    "add-feature",
+    "--title",
+    secondFeatureTitle,
+    "--slug",
+    "guest-request-notifications",
+    "--verify-cmd",
+    `${process.execPath} -e "process.exit(0)"`
+  ],
+  runTmp
+);
+assert(addFeatureOutput.includes(secondFeatureTitle), "add-feature should report the queued feature");
+const registryWithQueue = JSON.parse(fs.readFileSync(featureRegistryPath, "utf8"));
+assert.strictEqual(registryWithQueue.features.length, 2, "add-feature should append to the project queue");
+assert.strictEqual(registryWithQueue.features[1].status, "planned", "new features should remain planned");
+assert(
+  fs.existsSync(path.join(runTmp, registryWithQueue.features[1].path, "TASKS.md")),
+  "add-feature should create an execution packet for the queued feature"
+);
+
+const nextOutput = run(["next"], runTmp);
+assert(nextOutput.includes(path.basename(activeFeatureDir)), "next should identify the active feature");
+assert(nextOutput.includes("Add the first failing test"), "next should print the next pending action");
+
+const missingEvidenceOutput = runFailure(
+  ["complete-feature", "--verify-cmd", `${process.execPath} -e "process.exit(0)"`],
+  runTmp
+);
+assert(
+  missingEvidenceOutput.includes("--evidence"),
+  "complete-feature should require explicit verification evidence"
+);
+
+const completionOutput = run(
+  [
+    "complete-feature",
+    "--verify-cmd",
+    `${process.execPath} -e "process.exit(0)"`,
+    "--evidence",
+    "CLI lifecycle smoke verification passed"
+  ],
+  runTmp
+);
+assert(completionOutput.includes("Feature completed"), "complete-feature should report successful completion");
+const promotedState = JSON.parse(fs.readFileSync(path.join(runTmp, ".codebase", "state.json"), "utf8"));
+assert.strictEqual(
+  promotedState.current_state,
+  "IMPLEMENTATION",
+  "complete-feature should keep the project in implementation while queued work remains"
+);
+assert(
+  promotedState.active_feature.includes("guest-request-notifications"),
+  "complete-feature should promote the next planned feature"
+);
+assert(
+  promotedState.metrics.time_to_verified_feature_seconds >= 0,
+  "complete-feature should record feature lead-time telemetry"
+);
+const promotedRegistry = JSON.parse(fs.readFileSync(featureRegistryPath, "utf8"));
+assert.strictEqual(
+  promotedRegistry.features[0].status,
+  "verified",
+  "complete-feature should move the active feature to verified"
+);
+assert.strictEqual(
+  promotedRegistry.features[0].evidence,
+  "CLI lifecycle smoke verification passed",
+  "complete-feature should persist verification evidence"
+);
+assert.strictEqual(
+  promotedRegistry.features[1].status,
+  "in-progress",
+  "complete-feature should promote the next queued feature"
+);
+const featureIndexAfterCompletion = fs.readFileSync(path.join(runTmp, ".planning", "FEATURE_INDEX.md"), "utf8");
+assert(
+  featureIndexAfterCompletion.includes(`| ${promotedRegistry.features[0].title} | [x] |`),
+  "complete-feature should mark the feature complete in FEATURE_INDEX.md"
+);
+const lifecycleRunLog = path.join(
+  runTmp,
+  "observability",
+  "agent-runs",
+  `${promotedState.session_id}-feature-complete.json`
+);
+assert(fs.existsSync(lifecycleRunLog), "complete-feature should write an observability run record");
+const nextPromotedOutput = run(["next"], runTmp);
+assert(nextPromotedOutput.includes(secondFeatureTitle), "next should resolve the promoted feature");
+
+run(
+  [
+    "complete-feature",
+    "--verify-cmd",
+    `${process.execPath} -e "process.exit(0)"`,
+    "--evidence",
+    "Notification feature verification passed"
+  ],
+  runTmp
+);
+const verificationState = JSON.parse(fs.readFileSync(path.join(runTmp, ".codebase", "state.json"), "utf8"));
+assert.strictEqual(
+  verificationState.current_state,
+  "VERIFICATION",
+  "completing the final feature should move the project to verification"
+);
+assert.strictEqual(verificationState.active_feature, "", "final feature completion should clear active work");
+
+const prematureCompletion = runFailure(["complete-project", "--evidence", "Premature close"], runTmp);
+assert(
+  prematureCompletion.includes("RELEASE_READY"),
+  "complete-project should reject projects that have not passed project verification"
+);
+
+const projectVerificationOutput = run(
+  [
+    "verify-project",
+    "--verify-cmd",
+    `${process.execPath} -e "process.exit(0)"`,
+    "--evidence",
+    "Project acceptance suite passed"
+  ],
+  runTmp
+);
+assert(projectVerificationOutput.includes("Project verified"), "verify-project should report success");
+const releaseReadyState = JSON.parse(fs.readFileSync(path.join(runTmp, ".codebase", "state.json"), "utf8"));
+assert.strictEqual(
+  releaseReadyState.current_state,
+  "RELEASE_READY",
+  "verify-project should move the project to release readiness"
+);
+assert(
+  fs.existsSync(path.join(runTmp, ".planning", "PROJECT_VERIFICATION.json")),
+  "verify-project should persist project-level proof"
+);
+assert(
+  fs.existsSync(path.join(runTmp, ".planning", "IMPLEMENTATION_HANDOFF.md")),
+  "verify-project should create a final implementation handoff"
+);
+
+const projectCompletionOutput = run(
+  ["complete-project", "--evidence", "Release readiness approved"],
+  runTmp
+);
+assert(projectCompletionOutput.includes("Project completed"), "complete-project should close release-ready work");
+const completedState = JSON.parse(fs.readFileSync(path.join(runTmp, ".codebase", "state.json"), "utf8"));
+assert.strictEqual(completedState.current_state, "COMPLETED", "complete-project should close project state");
+const historyLength = completedState.history.length;
+const eventsPath = path.join(runArtifactDir, "EVENTS.jsonl");
+assert(fs.existsSync(eventsPath), "lifecycle transitions should create append-only run events");
+const eventCount = fs.readFileSync(eventsPath, "utf8").trim().split("\n").length;
+assert(eventCount >= 5, "event history should include queue, feature, verification, and completion transitions");
+
+const repeatedCompletionOutput = run(
+  ["complete-project", "--evidence", "Release readiness approved"],
+  runTmp
+);
+assert(repeatedCompletionOutput.includes("already completed"), "complete-project should be idempotent");
+const repeatedCompletionState = JSON.parse(fs.readFileSync(path.join(runTmp, ".codebase", "state.json"), "utf8"));
+assert.strictEqual(
+  repeatedCompletionState.history.length,
+  historyLength,
+  "idempotent completion should not duplicate state history"
+);
+assert.strictEqual(
+  fs.readFileSync(eventsPath, "utf8").trim().split("\n").length,
+  eventCount,
+  "idempotent completion should not duplicate lifecycle events"
+);
+
+const auditOutput = run(["pipeline-audit"], runTmp);
+assert(auditOutput.includes("Pipeline audit passed"), "pipeline-audit should validate the completed lifecycle");
+
 const statusOutput = run(["status"]);
 assert(statusOutput.includes("GENESIS HARNESS - STATUS REPORT"), "status should render status report");
 

package/tests/unit/repository_hygiene.test.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+"use strict";
+
+const assert = require("assert");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const repoRoot = path.resolve(__dirname, "..", "..");
+const hygieneScript = path.join(repoRoot, "scripts", "check-repository-hygiene.js");
+
+const output = execFileSync(process.execPath, [hygieneScript], {
+  cwd: repoRoot,
+  encoding: "utf8"
+});
+
+assert(output.includes("repository hygiene passed"), "hygiene gate should report success");
+console.log("repository_hygiene tests passed");

package/tests/unit/state_metadata.test.js

@@ -0,0 +1,76 @@
+const assert = require("assert");
+const fs = require("fs");
+const path = require("path");
+
+const repoRoot = path.resolve(__dirname, "..", "..");
+const currentStatePath = path.join(repoRoot, ".codebase", "CURRENT_STATE.md");
+const repoStatePath = path.join(repoRoot, ".codebase", "state.json");
+
+console.log("Running state metadata contract unit tests...");
+
+const currentState = fs.readFileSync(currentStatePath, "utf8");
+const repoState = JSON.parse(fs.readFileSync(repoStatePath, "utf8"));
+const allowedStates = new Set([
+  "INIT",
+  "REQUIREMENTS_GATHERING",
+  "PLANNING",
+  "IMPLEMENTATION",
+  "VERIFICATION",
+  "RELEASE_READY",
+  "COMPLETED"
+]);
+
+const latestSessionMatch = currentState.match(/\*\*Latest Session\*\*: `([^`]+)`/);
+assert(latestSessionMatch, "CURRENT_STATE.md should declare the latest session");
+assert.strictEqual(
+  repoState.session_id,
+  latestSessionMatch[1],
+  "state.json session_id should match CURRENT_STATE.md"
+);
+
+const ttfvMatch = currentState.match(/\*\*Time to First Verification \(TTFV\)\*\*: (\d+)s/);
+assert(ttfvMatch, "CURRENT_STATE.md should declare TTFV in seconds");
+assert.strictEqual(
+  repoState.ttfv_seconds,
+  Number(ttfvMatch[1]),
+  "state.json ttfv_seconds should match CURRENT_STATE.md"
+);
+assert(
+  repoState._comment_ttfv.includes(`${repoState.ttfv_seconds}s`),
+  "state.json TTFV comment should describe the same number of seconds"
+);
+
+assert(
+  allowedStates.has(repoState.current_state),
+  `state.json current_state must be one of: ${Array.from(allowedStates).join(", ")}`
+);
+
+const sessionStartedAt = Date.parse(repoState.session_started_at);
+assert(!Number.isNaN(sessionStartedAt), "state.json should include a valid session_started_at timestamp");
+
+if (repoState.current_state === "COMPLETED") {
+  const completedAt = Date.parse(repoState.completed_at);
+  assert(!Number.isNaN(completedAt), "completed state should include a valid completed_at timestamp");
+  assert(
+    completedAt >= sessionStartedAt,
+    "state.json completed_at must not be older than session_started_at"
+  );
+} else {
+  assert(
+    !Object.prototype.hasOwnProperty.call(repoState, "completed_at"),
+    "active states should not retain a stale completed_at timestamp"
+  );
+}
+
+for (const transition of repoState.history || []) {
+  assert(
+    allowedStates.has(transition.from),
+    `history transition.from must be a legal state: ${transition.from}`
+  );
+  assert(
+    allowedStates.has(transition.to),
+    `history transition.to must be a legal state: ${transition.to}`
+  );
+}
+
+console.log("state metadata contract tests passed! ✓\n");

package/tests/unit/verify_gate.test.js

@@ -0,0 +1,25 @@
+const assert = require("assert");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const repoRoot = path.resolve(__dirname, "..", "..");
+const cli = path.join(repoRoot, "bin", "genesis-harness.js");
+
+console.log("Running verify-gate contract unit tests...");
+
+const output = execFileSync(process.execPath, [cli, "verify-gate"], {
+  cwd: repoRoot,
+  env: {
+    ...process.env,
+    GENESIS_VERIFY_GATE_SELF_TEST: "1"
+  },
+  encoding: "utf8"
+});
+
+assert(output.includes("run-evals.sh"), "verify-gate should include eval regression checks");
+assert(output.includes("docs-gate"), "verify-gate should include docs drift checks");
+assert(output.includes("cold-start"), "verify-gate should include cold-start readiness checks");
+assert(output.includes("pack:check"), "verify-gate should include package dry-run checks");
+assert(output.includes("leanctx"), "verify-gate should include lean context reporting");
+
+console.log("verify-gate contract tests passed! ✓\n");