codex-genesis-harness 0.1.7 → 0.1.8

package/contracts/features/registry-schema.json

@@ -0,0 +1,15 @@
+{
+  "version": "1.0.0",
+  "description": "Schema for features/REGISTRY.md — the canonical machine-readable feature list primitive (L08 Harness Engineering)",
+  "changed_at": "2026-06-03T02:37:00Z",
+  "required_columns": ["id", "status", "title", "verify_cmd", "skill"],
+  "valid_statuses": ["planned", "in-progress", "done", "verified", "deprecated"],
+  "notes": "Every feature MUST have a verify_cmd. 'verified' status requires evidence from the last CI run.",
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "date": "2026-06-03",
+      "change": "Initial schema — establishes feature list as harness primitive per L08"
+    }
+  ]
+}

package/contracts/observability/agent-run-schema.json

@@ -0,0 +1,34 @@
+{
+  "version": "1.0.0",
+  "description": "Schema for observability/agent-runs/*.json — records of agent execution sessions (L11 Harness Engineering)",
+  "changed_at": "2026-06-03T02:37:00Z",
+  "required_fields": [
+    "session_id",
+    "timestamp",
+    "skill",
+    "phase",
+    "outcome",
+    "evidence"
+  ],
+  "field_types": {
+    "session_id": "string — unique identifier for the agent session (e.g. UUID or date-prefixed slug)",
+    "timestamp": "ISO 8601 string",
+    "skill": "string — name of the genesis skill invoked",
+    "phase": "string — one of: init, plan, execute, verify, handoff",
+    "outcome": "string — one of: success, failure, partial, skipped",
+    "evidence": "string — CLI output snippet or file path proving the outcome"
+  },
+  "optional_fields": {
+    "task_id": "string — task item from task.md this run belongs to",
+    "duration_ms": "number — wall-clock time of the session",
+    "tokens_used": "number — approximate tokens consumed",
+    "recovery_needed": "boolean — whether a recovery point was consulted"
+  },
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "date": "2026-06-03",
+      "change": "Initial schema — establishes observability as first-class harness artifact per L11"
+    }
+  ]
+}

package/contracts/observability/failure-schema.json

@@ -0,0 +1,35 @@
+{
+  "version": "1.0.0",
+  "description": "Schema for observability/failures/*.json — records agent failures for post-mortem analysis (L11 Harness Engineering)",
+  "changed_at": "2026-06-03T02:37:00Z",
+  "required_fields": [
+    "failure_id",
+    "timestamp",
+    "skill",
+    "phase",
+    "error_type",
+    "error_message",
+    "recovery_action"
+  ],
+  "field_types": {
+    "failure_id": "string — unique id for the failure event",
+    "timestamp": "ISO 8601 string",
+    "skill": "string — skill that was active when failure occurred",
+    "phase": "string — one of: init, plan, execute, verify, handoff",
+    "error_type": "string — one of: assertion, timeout, permission, contract_violation, scope_overreach, under_finish",
+    "error_message": "string — exact CLI error output or description",
+    "recovery_action": "string — what was done to recover (e.g. 'reverted via git checkout', 'resumed from RECOVERY_POINTS.md')"
+  },
+  "optional_fields": {
+    "session_id": "string — cross-reference to agent-runs/ entry",
+    "root_cause": "string — 5-why analysis result",
+    "prevention": "string — what harness change prevents recurrence"
+  },
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "date": "2026-06-03",
+      "change": "Initial schema — failure observability as harness primitive"
+    }
+  ]
+}

package/contracts/ui/auth/login-screen-contract.json

@@ -0,0 +1,43 @@
+{
+  "contract_id": "UI-AUTH-LOGIN",
+  "version": "1.0.0",
+  "description": "Concrete example of a UI contract for the demo login feature. Defines inputs, visual states, and outputs.",
+  "inputs": {
+    "data": [
+      {
+        "name": "email",
+        "type": "string",
+        "validation": "Valid email format",
+        "required": true
+      },
+      {
+        "name": "password",
+        "type": "string",
+        "validation": "Minimum 8 characters",
+        "required": true
+      }
+    ]
+  },
+  "states": {
+    "initial": "Empty fields, disabled submit button.",
+    "valid": "Both fields pass validation, submit button enabled with cyan neon glow.",
+    "loading": "Submit button shows spinner, fields disabled.",
+    "error": "Error message displayed below fields, fields have red error outline."
+  },
+  "outputs": {
+    "events": [
+      {
+        "name": "onLoginSubmit",
+        "payload": {
+          "email": "string",
+          "passwordHash": "string"
+        }
+      },
+      {
+        "name": "onGoogleSignIn",
+        "payload": null
+      }
+    ]
+  },
+  "mockup_reference": ".planning/features/auth/mockup-login.png"
+}

package/features/REGISTRY.md

@@ -0,0 +1,63 @@
+# Feature Registry
+
+> **Nguồn sự thật duy nhất** cho tất cả tính năng của Genesis Codex Harness.  
+> Schema: [`contracts/features/registry-schema.json`](../contracts/features/registry-schema.json)  
+> **RULE**: Mỗi feature phải có `verify_cmd` — lệnh thực thi xác nhận tính năng hoạt động.
+
+## Status Definitions
+
+| Status | Ý nghĩa |
+|---|---|
+| `planned` | Đã xác định scope, chưa implement |
+| `in-progress` | Đang được implement trong phiên hiện tại |
+| `done` | Code xong, chưa chạy verification gate |
+| `verified` | Đã có CLI evidence — verification passed |
+| `deprecated` | Không còn được duy trì |
+
+---
+
+## Feature Table
+
+| id | status | title | verify_cmd | skill |
+|---|---|---|---|---|
+| F001 | verified | Skill system — 25 packaged Codex skills | `bash scripts/verify.sh` | genesis-harness |
+| F002 | verified | CLI binary `genesis-harness` với install/uninstall/status/docs | `node tests/integration/cli-smoke.test.js` | genesis-harness |
+| F003 | verified | LeanCTX context budget policy seeding | `bash scripts/run-evals.sh` | genesis-harness |
+| F004 | verified | Beads memory system (remember/recall/forget/prime) | `bash scripts/run-evals.sh` | genesis-harness |
+| F005 | verified | Mermaid VISUAL_GRAPH.md sync gate | `bash scripts/run-evals.sh` | genesis-harness |
+| F006 | verified | docs-gate hook (check-docs-sync.sh) | `node bin/genesis-harness.js docs-gate` | genesis-harness |
+| F007 | verified | PEV Loop enforcement (Plan → Execute → Verify) | `bash scripts/verify.sh` | genesis-harness-engineering |
+| F008 | verified | Contract system (api/agents/events/ui) | `bash scripts/verify.sh` | genesis-api-contract |
+| F009 | verified | TDD workflow (Red → Green → Refactor) | `node tests/unit/feature_registry.test.js` | genesis-test-driven-development |
+| F010 | verified | Verification-before-completion gate | `bash scripts/verify.sh` | genesis-verification-before-completion |
+| F011 | verified | git worktrees isolation for dangerous changes | `bash scripts/verify.sh .codex/skills/genesis-using-git-worktrees` | genesis-using-git-worktrees |
+| F012 | verified | Observability schema + live data (L11) | `node tests/unit/feature_registry.test.js` | genesis-observability-automation |
+| F013 | verified | Feature Registry as harness primitive (L08) | `node tests/unit/feature_registry.test.js` | genesis-harness-engineering |
+| F014 | verified | npm pack / tarball smoke test | `bash scripts/run-evals.sh` | genesis-release |
+| F015 | verified | spec-impact-engine propagation chain | `bash scripts/verify.sh .codex/skills/spec-impact-engine` | spec-impact-engine |
+| F016 | in-progress | Cold-start test automation (L03) | `node scripts/cold-start-check.js` | genesis-harness |
+| F017 | planned | Per-session Time-to-First-Verification KPI (L06) | `node bin/genesis-harness.js status --ttfv` | genesis-harness |
+| F018 | planned | Scope ledger per task (L07) | `bash scripts/check-scope.sh` | genesis-harness |
+| F019 | verified | Demo Feature (Mockup + Contract + E2E) | `npm test` (or npx playwright test) | genesis-harness-engineering |
+
+---
+
+## Verification Evidence (Last Run)
+
+> Update this section after each CI run.
+
+```
+Date: 2026-06-03T02:38:00Z
+scripts/verify.sh       → verify passed
+scripts/run-evals.sh    → evals passed
+feature_registry.test.js → feature_registry tests passed
+```
+
+---
+
+## Adding a New Feature
+
+1. Add a row to the Feature Table above with a **unique `id`** and a **real `verify_cmd`**
+2. Set initial status to `planned`
+3. Update `.codebase/MODULE_INDEX.md` if new module is introduced
+4. Run `node tests/unit/feature_registry.test.js` — must pass before status → `verified`

package/features/SCOPE-template.md

@@ -0,0 +1,65 @@
+# SCOPE — [Task Name]
+
+> **File**: `.planning/tasks/[task-id]/SCOPE.md`  
+> **Purpose**: Hard boundary definition — lists exactly which files this task MAY modify.  
+> **Rule**: Agent MUST NOT touch any file not listed below. If a necessary file is missing, update this SCOPE.md first and get confirmation.
+
+---
+
+## Task ID
+`[task-id]` — e.g. `F013-feature-registry`
+
+## Task Description
+[One-sentence description of what this task does]
+
+## Skill
+`[genesis-skill-name]` — the skill governing this task
+
+---
+
+## Permitted File Changes
+
+### ✅ Files this task MAY create or modify
+
+```
+[list each file on its own line, relative to repo root]
+features/REGISTRY.md
+contracts/features/registry-schema.json
+tests/unit/feature_registry.test.js
+.codebase/MODULE_INDEX.md
+scripts/run-evals.sh
+```
+
+### ❌ Files this task MUST NOT touch
+
+```
+[list critical files that must not be affected]
+.codex/SOUL.md
+AGENTS.md
+package.json (unless adding to 'files' array only)
+```
+
+### 🟡 Files requiring explicit confirmation before touching
+
+```
+[files that might need updating but require user review first]
+scripts/verify.sh
+.codebase/state.json
+```
+
+---
+
+## Scope Boundary Rationale
+
+[Why these boundaries? What would happen if the agent went outside them?]
+
+Example: "Restricting to `features/` and `contracts/features/` prevents accidental changes to the core verification loop while adding the registry primitive."
+
+---
+
+## Scope Check Command
+
+```bash
+# Verify no out-of-scope files were modified:
+bash scripts/check-scope.sh .planning/tasks/[task-id]/SCOPE.md
+```

package/fixtures/planning/MOCKUP_PROMPT_TEMPLATE.md

@@ -0,0 +1,16 @@
+# Mockup Generation Instruction
+
+**Mục đích:** Bắt buộc AI Agent phải tạo ra bản nháp giao diện (Mockup) trực quan trước khi bắt đầu code bất kỳ file UI nào.
+
+## Chỉ thị cho AI Agent:
+Khi người dùng yêu cầu thiết kế một tính năng mới có giao diện người dùng (UI):
+1. **Dừng viết code ngay lập tức.** Không tạo file `.tsx`, `.html`, `.css` nào.
+2. Dùng công cụ `generate_image` (nếu có) để tạo ra một bản thiết kế UI Mockup dựa trên mô tả của người dùng.
+   - **Prompt cho generate_image:** Cần miêu tả chi tiết: Bố cục (Layout), Màu sắc (Colors), Nút bấm (Buttons), Trạng thái (States), và Phong cách (Style - ví dụ: Glassmorphism, Dark mode, Minimalist).
+3. Sau khi ảnh được tạo thành công trong thư mục Artifacts:
+   - Hãy dùng lệnh terminal để copy file ảnh đó vào thư mục `.planning/features/<tên-tính-năng>/mockup.png`.
+   - Ví dụ: `mkdir -p .planning/features/auth && cp <đường-dẫn-ảnh-từ-artifact> .planning/features/auth/mockup.png`
+4. Cập nhật `features/REGISTRY.md` để map tính năng này với file mockup vừa lưu.
+5. Chỉ khi người dùng **phê duyệt (Approve)** ảnh Mockup đó, bạn mới được phép bắt đầu viết code Frontend.
+
+> **Lý do:** Harness tuân thủ PEV Loop (Plan -> Execute -> Verify). Việc code UI mù mờ không có mockup được xem là vi phạm bước Plan.

package/observability/agent-runs/sample-run.json

@@ -0,0 +1,13 @@
+{
+  "session_id": "2026-06-03-harness-engineering-L08-L11",
+  "timestamp": "2026-06-03T02:37:00Z",
+  "skill": "genesis-harness-engineering",
+  "phase": "execute",
+  "outcome": "success",
+  "evidence": "scripts/verify.sh exits 0; scripts/run-evals.sh exits 0; node tests/unit/feature_registry.test.js -> 'feature_registry tests passed'",
+  "task_id": "P1.1-feature-registry + P1.2-observability-live",
+  "duration_ms": 120000,
+  "tokens_used": 0,
+  "recovery_needed": false,
+  "_note": "This is the bootstrap sample demonstrating the observability format. Future agent runs should append new JSON files to this directory using the same schema (contracts/observability/agent-run-schema.json)."
+}

package/observability/decision-logs/sample-decision.md

@@ -0,0 +1,43 @@
+# Decision: Feature Registry as Harness Primitive (L08)
+
+**Date**: 2026-06-03  
+**Session**: `2026-06-03-harness-engineering-L08-L11`  
+**Skill**: `genesis-harness-engineering`
+
+## Decision
+
+Establish `features/REGISTRY.md` as the **single machine-readable source of truth** for all project features. Each feature entry must include: unique `id`, `status`, `title`, `verify_cmd` (executable verification command), and owning `skill`.
+
+## Reason
+
+**Harness Engineering Lecture 08** identifies the feature list as a "harness primitive" — not human prose, but an executable record the harness can validate. The previous state had features scattered across `ROADMAP.md` (prose) and `EVOLUTION_PLAN.md` (markdown narrative), with no per-feature verification command and no machine-readable status.
+
+This meant:
+1. An agent couldn't know which features were truly "verified" vs. "claimed done"
+2. No CI gate could enforce feature status transitions
+3. The harness couldn't generate per-feature test evidence
+
+The fix closes this gap by creating a structured registry that `run-evals.sh` can parse and `feature_registry.test.js` can validate.
+
+## Rejected Options
+
+- **Option A**: Use a JSON file instead of Markdown table  
+  *Rejected*: Markdown table is both human-readable and parseable. Keeps the "docs are code" principle without sacrificing discoverability.
+
+- **Option B**: Use GitHub Issues as the feature list  
+  *Rejected*: Violates L03 (repo is the single source of truth). External systems cannot be the harness primitive.
+
+- **Option C**: Derive the list from `.planning/ROADMAP.md` automatically  
+  *Rejected*: ROADMAP.md is narrative; auto-parsing prose is fragile. Explicit registry is safer.
+
+## Verification
+
+```
+node tests/unit/feature_registry.test.js
+→ feature_registry tests passed
+
+scripts/run-evals.sh (L08 gate section)
+→ evals passed
+```
+
+Both gates pass with exit code 0 after implementation. Failure record before fix: `observability/failures/sample-failure.json`.

package/observability/failures/sample-failure.json

@@ -0,0 +1,12 @@
+{
+  "failure_id": "2026-06-03-pre-fix-L08-missing-registry",
+  "timestamp": "2026-06-03T02:36:50Z",
+  "skill": "genesis-harness-engineering",
+  "phase": "verify",
+  "error_type": "assertion",
+  "error_message": "AssertionError: L08: features/REGISTRY.md must exist as machine-readable feature primitive",
+  "recovery_action": "Created features/REGISTRY.md + contracts/features/registry-schema.json + observability schemas as implementation fix",
+  "session_id": "2026-06-03-harness-engineering-L08-L11",
+  "root_cause": "Feature list existed only as human-readable prose in ROADMAP.md. No machine-readable canonical source of truth for feature status existed (violates L08 principle).",
+  "prevention": "Added verify gate in run-evals.sh that checks REGISTRY.md presence + schema validity. Test now in tests/unit/feature_registry.test.js ensures regression cannot re-occur."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-genesis-harness",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Hệ thống quản trị (Harness) dành cho AI Agent (Codex) với cơ chế FSM State Persistence, Validation Gates và Test-First Workflow. Đảm bảo agent không bị trôi context.",
   "license": "MIT",
   "bin": {
@@ -15,13 +15,15 @@
     "test:gen": "node scripts/test_generator.js",
     "sentinel": "node scripts/prompt_sentinel.js",
     "integrity": "node scripts/contract_integrity_gate.js",
-    "telemetry": "node scripts/healing_telemetry.js"
+    "telemetry": "node scripts/healing_telemetry.js",
+    "mcp:setup": "node bin/genesis-harness.js mcp"
   },
   "files": [
     ".codex-plugin",
     ".codex/skills",
     ".codebase",
     "contracts",
+    "features",
     "fixtures",
     "tests",
     "playwright",
@@ -64,5 +66,9 @@
   "funding": {
     "type": "momo",
     "url": "tel:0865814259"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.29.7",
+    "@babel/traverse": "^7.29.7"
   }
-}
+}

package/playwright/e2e/app-template.spec.js

@@ -0,0 +1,37 @@
+const { test, expect, devices } = require('@playwright/test');
+
+/**
+ * MOBILE APP E2E TEST TEMPLATE
+ * Dành cho các ứng dụng Mobile App (React Native Web, PWA, hoặc Mobile Viewport testing)
+ * Lưu ý: Nếu test Native App thực sự (iOS/Android), dự án cần chuyển sang dùng Appium hoặc Detox.
+ * File này dùng Playwright Mobile Emulation để test App logic trên trình duyệt di động.
+ */
+test.describe('Mobile App Feature Flow', () => {
+  // Use a mobile device profile for emulation
+  test.use({ ...devices['iPhone 13'] });
+
+  test.beforeEach(async ({ page }) => {
+    // Replace with the actual URL of the Mobile Web / React Native Web server
+    await page.goto('http://localhost:8081');
+  });
+
+  test('should render mobile-specific layout (Hamburger menu)', async ({ page }) => {
+    // In mobile view, the hamburger menu should be visible instead of desktop navbar
+    const hamburgerBtn = page.locator('[aria-label="Open Menu"]');
+    await expect(hamburgerBtn).toBeVisible();
+    
+    // Tap the menu
+    await hamburgerBtn.click();
+    await expect(page.locator('.mobile-drawer')).toBeVisible();
+  });
+
+  test('should support touch interactions and swipe', async ({ page }) => {
+    // Simulating touch actions on a mobile carousel or list
+    const listItem = page.locator('.list-item').first();
+    await expect(listItem).toBeVisible();
+    
+    // Playwright touch simulation (if applicable to the web-mobile app)
+    await listItem.tap();
+    await expect(page.locator('.item-details')).toBeVisible();
+  });
+});

package/playwright/e2e/auth/login-screen.spec.js

@@ -0,0 +1,65 @@
+const { test, expect } = require('@playwright/test');
+
+/**
+ * Concrete E2E Test Example for Demo Login Feature
+ * Contract Reference: contracts/ui/auth/login-screen-contract.json
+ * Mockup Reference: .planning/features/auth/mockup-login.png
+ */
+test.describe('UI-AUTH-LOGIN Contract Implementation', () => {
+  test.beforeEach(async ({ page }) => {
+    // Navigate to the demo app's login page (replace with actual dev server URL in real projects)
+    // For this harness template, we intercept the route to mock a UI
+    await page.route('**/login', route => {
+      route.fulfill({
+        status: 200,
+        contentType: 'text/html',
+        body: `
+          <html>
+            <body>
+              <form id="login-form">
+                <input type="email" id="email" required />
+                <input type="password" id="password" required minlength="8" />
+                <button type="submit" id="sign-in-btn" disabled>Sign In</button>
+                <button type="button" id="google-btn">Sign in with Google</button>
+              </form>
+              <div id="error-msg" style="display: none;"></div>
+              <script>
+                const email = document.getElementById('email');
+                const pwd = document.getElementById('password');
+                const btn = document.getElementById('sign-in-btn');
+                const checkValid = () => {
+                  btn.disabled = !(email.value.includes('@') && pwd.value.length >= 8);
+                };
+                email.addEventListener('input', checkValid);
+                pwd.addEventListener('input', checkValid);
+              </script>
+            </body>
+          </html>
+        `
+      });
+    });
+    
+    await page.goto('http://localhost:3000/login');
+  });
+
+  test('Initial state: fields are empty and submit button is disabled', async ({ page }) => {
+    const emailInput = page.locator('#email');
+    const pwdInput = page.locator('#password');
+    const submitBtn = page.locator('#sign-in-btn');
+
+    await expect(emailInput).toBeEmpty();
+    await expect(pwdInput).toBeEmpty();
+    await expect(submitBtn).toBeDisabled();
+  });
+
+  test('Valid state: entering valid email and password enables submit button', async ({ page }) => {
+    const emailInput = page.locator('#email');
+    const pwdInput = page.locator('#password');
+    const submitBtn = page.locator('#sign-in-btn');
+
+    await emailInput.fill('user@example.com');
+    await pwdInput.fill('securepassword123');
+
+    await expect(submitBtn).toBeEnabled();
+  });
+});

package/playwright/e2e/web-template.spec.js

@@ -0,0 +1,28 @@
+const { test, expect } = require('@playwright/test');
+
+/**
+ * WEB E2E TEST TEMPLATE
+ * Dành cho các dự án Web App (Next.js, React, Vue, v.v.)
+ */
+test.describe('Web App Feature Flow', () => {
+  test.beforeEach(async ({ page }) => {
+    // Replace with the actual URL or local dev server of the Web App
+    await page.goto('http://localhost:3000');
+  });
+
+  test('should display the main Web UI component', async ({ page }) => {
+    // Example: verify a specific web element is visible
+    const mainHeading = page.locator('h1');
+    await expect(mainHeading).toBeVisible();
+    await expect(mainHeading).toHaveText('Welcome to Web App');
+  });
+
+  test('should handle web form submission', async ({ page }) => {
+    // Example: fill out a web form and submit
+    await page.fill('input[name="username"]', 'testuser');
+    await page.click('button[type="submit"]');
+    
+    // Verify success state
+    await expect(page.locator('.success-message')).toBeVisible();
+  });
+});

package/scripts/check-scope.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# check-scope.sh — L07 Scope Ledger Enforcement
+# Usage: bash scripts/check-scope.sh [SCOPE.md path] [optional: git diff base]
+#
+# Reads a SCOPE.md file and verifies that all modified files (from git diff)
+# are within the permitted boundaries defined in the scope ledger.
+#
+# Exit codes:
+#   0 = all changes within scope
+#   1 = out-of-scope changes detected
+#   2 = SCOPE.md not found or invalid
+
+set -euo pipefail
+
+SCOPE_FILE="${1:-}"
+GIT_BASE="${2:-HEAD}"
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+fail() {
+  echo "scope-check FAIL: $*" >&2
+  exit 1
+}
+
+warn() {
+  echo "scope-check WARN: $*" >&2
+}
+
+if [ -z "$SCOPE_FILE" ]; then
+  echo "Usage: bash scripts/check-scope.sh <SCOPE.md path> [git-base]"
+  echo "       If no SCOPE.md is provided, scope check is advisory only."
+  echo "scope-check: no scope file provided — skipping (advisory mode)"
+  exit 0
+fi
+
+if [ ! -f "$SCOPE_FILE" ]; then
+  echo "scope-check: SCOPE.md not found at '$SCOPE_FILE' — using advisory mode (no hard boundary)"
+  echo "scope-check: Create '$SCOPE_FILE' from features/SCOPE-template.md to enable enforcement."
+  exit 0
+fi
+
+echo "scope-check: Enforcing boundaries from '$SCOPE_FILE'..."
+
+# Extract permitted files section (lines between "## Permitted File Changes" and next ##)
+PERMITTED=$(awk '/^### ✅ Files this task MAY create or modify/{found=1; next} /^### /{found=0} found && /^[a-zA-Z_.\/-]/{print $0}' "$SCOPE_FILE")
+
+if [ -z "$PERMITTED" ]; then
+  warn "No permitted files extracted from '$SCOPE_FILE' — check format. Skipping enforcement."
+  exit 0
+fi
+
+# Get list of changed files
+if git rev-parse --git-dir > /dev/null 2>&1; then
+  CHANGED=$(git diff --name-only "$GIT_BASE" 2>/dev/null || git status --porcelain | awk '{print $2}')
+else
+  echo "scope-check: not inside a git repo — using git status fallback"
+  CHANGED=$(git status --porcelain 2>/dev/null | awk '{print $2}' || echo "")
+fi
+
+if [ -z "$CHANGED" ]; then
+  echo "scope-check: no changed files detected — scope check trivially passes"
+  exit 0
+fi
+
+OUT_OF_SCOPE=()
+while IFS= read -r changed_file; do
+  [ -z "$changed_file" ] && continue
+  IN_SCOPE=false
+  while IFS= read -r permitted; do
+    [ -z "$permitted" ] && continue
+    # Check if changed file matches permitted entry (exact or prefix)
+    if [[ "$changed_file" == "$permitted" ]] || [[ "$changed_file" == "$permitted"* ]]; then
+      IN_SCOPE=true
+      break
+    fi
+  done <<< "$PERMITTED"
+  if [ "$IN_SCOPE" = false ]; then
+    OUT_OF_SCOPE+=("$changed_file")
+  fi
+done <<< "$CHANGED"
+
+if [ ${#OUT_OF_SCOPE[@]} -gt 0 ]; then
+  echo "scope-check FAIL: The following files are outside the permitted scope:"
+  for f in "${OUT_OF_SCOPE[@]}"; do
+    echo "  ❌ $f"
+  done
+  echo ""
+  echo "To expand scope: edit '$SCOPE_FILE' and add the file to '## Permitted File Changes'."
+  echo "To override: add the file to '🟡 Files requiring explicit confirmation' and get user approval."
+  
+  if [ "${VIBE_MODE:-0}" = "1" ]; then
+    echo "scope-check WARN: VIBE_MODE is active. Bypassing fatal blocker."
+    echo "- [$(date -u +"%Y-%m-%dT%H:%M:%SZ")] VIBE_MODE Bypass: ${#OUT_OF_SCOPE[@]} files modified out of scope. Files: ${OUT_OF_SCOPE[*]}" >> "$repo_root/.codebase/TECH_DEBT.md"
+    exit 0
+  fi
+  
+  exit 1
+fi
+
+echo "scope-check passed: all ${#OUT_OF_SCOPE[@]} changed files are within scope"
+echo "scope-check: $(echo "$CHANGED" | wc -l | tr -d ' ') files changed, all permitted"