gaia-framework 1.58.0 → 1.59.0

package/_gaia/testing/workflows/test-automation/instructions.xml

@@ -0,0 +1,49 @@
+<workflow name="test-automation">
+<critical>
+  <mandate>Identify coverage gaps before writing new tests</mandate>
+  <mandate>Load unit testing knowledge for the project stack</mandate>
+  <mandate>Story must be in review status before test automation</mandate>
+  <mandate>Output must include machine-readable PASSED or FAILED verdict</mandate>
+  <mandate>When reading or running application source code, use {project-path} as the base directory — NOT {project-root}. {project-path} is resolved by the engine from global.yaml.</mandate>
+</critical>
+<step n="1" title="Load Story and Code">
+  <action>Resolve story file: search for {story_key}-*.md in {implementation_artifacts}/ using glob pattern to match the full filename ({story_key}-{title_slug}.md)</action>
+  <action>Read story file, identify files changed and acceptance criteria</action>
+  <action>Read implemented code files</action>
+</step>
+<step n="2" title="Status Gate">
+  <action>Verify story is in 'review' status</action>
+  <check if="status != review">HALT: Story must be in review status before test automation</check>
+</step>
+<step n="3" title="Identify Coverage Gaps">
+  <action>Analyze existing tests vs code paths</action>
+</step>
+<step n="4" title="Load Knowledge">
+  <action>Load unit test patterns for the project's stack from {knowledge_path}/</action>
+</step>
+<step n="5" title="Generate Tests">
+  <action>Write tests for uncovered code paths</action>
+  <action>Follow AAA pattern and naming conventions</action>
+</step>
+<step n="6" title="Run and Validate">
+  <action>Execute tests, verify they pass and cover intended paths</action>
+  <action>If ALL tests pass: verdict is PASSED</action>
+  <action>If ANY test fails: verdict is FAILED — list failing tests with reasons</action>
+</step>
+<step n="7" title="Generate Report">
+  <action>Generate automation report with coverage gaps filled and test results</action>
+  <template-output file="{test_artifacts}/{story_key}-test-automation.md">
+    Generate automation report with coverage gaps filled, test results, and machine-readable verdict (PASSED/FAILED).
+  </template-output>
+</step>
+<step n="8" title="Update Review Gate and Transition">
+  <action>Read story file, locate Review Gate table</action>
+  <action>If PASSED: update Test Automation row status to PASSED, link report file</action>
+  <action>If FAILED: update Test Automation row status to FAILED, link report file. Do NOT change story status — the review-gate-check protocol or run-all-reviews orchestrator handles status transitions.</action>
+  <template-output file="{implementation_artifacts}/{story_key}-*.md">
+    Update story file Review Gate table with test automation result and report link.
+  </template-output>
+  <action>Inform user: "Note: sprint-status.yaml may now be out of sync. Run /gaia-sprint-status to reconcile."</action>
+  <invoke-protocol name="review-gate-check" file="{project-root}/_gaia/core/protocols/review-gate-check.xml" />
+</step>
+</workflow>

package/_gaia/testing/workflows/test-automation/workflow.yaml

@@ -0,0 +1,11 @@
+name: test-automation
+description: 'Expand test automation coverage for codebase'
+module: testing
+agent: test-architect
+config_resolved: "{installed_path}/.resolved/test-automation.yaml"
+config_source: "{project-root}/_gaia/testing/config.yaml"
+installed_path: "{project-root}/_gaia/testing/workflows/test-automation"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+output:
+  primary: "{test_artifacts}/{story_key}-test-automation.md"

package/_gaia/testing/workflows/test-design/checklist.md

@@ -0,0 +1,9 @@
+# Test Design Checklist
+- [ ] Project context loaded and understood
+- [ ] Risk assessment completed with probability × impact ratings
+- [ ] Test levels defined per component
+- [ ] Test pyramid applied appropriately
+- [ ] Legacy integration boundaries identified and tested (if brownfield)
+- [ ] Data migration validation tests defined (if applicable)
+- [ ] Coverage targets defined
+- [ ] Quality gates specified for CI

package/_gaia/testing/workflows/test-design/instructions.xml

@@ -0,0 +1,47 @@
+<workflow name="test-design">
+<critical>
+  <mandate>Start with risk assessment — not all areas need equal coverage</mandate>
+  <mandate>Define quality gates for CI pipeline</mandate>
+</critical>
+<step n="1" title="Load Project Context">
+  <action>Read architecture doc, PRD, or project-context.md</action>
+  <action>Understand system components and their interactions</action>
+</step>
+<step n="2" title="Risk Assessment">
+  <action>Identify high-risk areas: revenue-critical, security-sensitive, complex logic</action>
+  <action>Rate each area: probability × impact</action>
+</step>
+<step n="3" title="Legacy Integration Boundaries (Brownfield)" optional="true">
+  <action>If PRD contains "Mode: Brownfield" or project has brownfield-assessment.md: activate this step</action>
+  <action>Identify integration boundaries: where new code calls legacy code and vice versa</action>
+  <action>For each boundary: define contract test (input/output schema validation between old and new)</action>
+  <action>For each legacy API wrapper or adapter: define adapter test (legacy behavior preserved)</action>
+  <action>If data migration exists: define migration validation tests (row counts, data integrity, rollback verification)</action>
+  <action>If dual-write strategy: define consistency tests (both stores reflect same state)</action>
+  <action>Add legacy boundary risks to risk assessment from step 2</action>
+</step>
+<step n="4" title="Test Strategy">
+  <action>Define test levels per component: unit, integration, E2E, contract</action>
+  <action>Apply test pyramid — most tests at lowest effective level</action>
+</step>
+<step n="5" title="Test Plan">
+  <action>Create test plan with coverage targets per component</action>
+  <action>Define test naming conventions and organization</action>
+</step>
+<step n="6" title="Quality Gates">
+  <action>Define automated gates: coverage %, pass rate, performance budgets</action>
+</step>
+<step n="7" title="Generate Output">
+  <action>Compile test plan with risk assessment, strategy, and quality gates</action>
+  <template-output file="{test_artifacts}/test-plan.md" />
+</step>
+<step n="8" title="Optional: Scaffold Test Framework">
+  <action>Check if the project already has a test framework configured (look for jest.config, vitest.config, playwright.config, pytest.ini, build.gradle test blocks, etc.)</action>
+  <ask>Would you like to scaffold the test framework now? /gaia-test-framework will detect your stack, generate config files, folder structure, fixture patterns, and a sample test. Recommended if no test framework is installed yet. (yes/no)</ask>
+  <action>If yes: run /gaia-test-framework</action>
+  <action>If no: skip — you can run /gaia-test-framework anytime later</action>
+</step>
+<next-step source="lifecycle-sequence.yaml">
+  <primary command="/gaia-create-epics">Break requirements into epics and stories (test plan is required before this step)</primary>
+</next-step>
+</workflow>

package/_gaia/testing/workflows/test-design/workflow.yaml

@@ -0,0 +1,11 @@
+name: test-design
+description: 'Create system-level or epic-level test plans'
+module: testing
+agent: test-architect
+config_resolved: "{installed_path}/.resolved/test-design.yaml"
+config_source: "{project-root}/_gaia/testing/config.yaml"
+installed_path: "{project-root}/_gaia/testing/workflows/test-design"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+output:
+  primary: "{test_artifacts}/test-plan.md"

package/_gaia/testing/workflows/test-framework/checklist.md

@@ -0,0 +1,8 @@
+# Test Framework Checklist
+- [ ] Project stack detected correctly
+- [ ] Framework recommendation matches stack
+- [ ] Config files generated
+- [ ] Folder structure scaffolded
+- [ ] Test runner script configured and executable (e.g., npm test)
+- [ ] Fixture architecture designed
+- [ ] No actual test implementations created — tests are written in Phase 4

package/_gaia/testing/workflows/test-framework/instructions.xml

@@ -0,0 +1,25 @@
+<workflow name="test-framework">
+<critical>
+  <mandate>Detect project stack before recommending framework</mandate>
+  <mandate>Scaffold complete setup: config files, folder structure, npm scripts (or equivalent). Do NOT implement or run any tests — test implementation happens in Phase 4 workflows (/gaia-dev-story, /gaia-qa-tests, /gaia-atdd).</mandate>
+</critical>
+<step n="1" title="Detect Stack">
+  <action>Identify project language, framework, and existing test setup</action>
+</step>
+<step n="2" title="Select Framework">
+  <action>Recommend test framework: Playwright/Cypress for E2E, Jest/Vitest/pytest/JUnit for unit</action>
+  <action>Consider existing project conventions</action>
+</step>
+<step n="3" title="Scaffold">
+  <action>Generate config files, folder structure, and test runner scripts. Do NOT write sample tests or run any test suite — only set up the infrastructure so tests can be added later.</action>
+  <action>Load fixture-architecture knowledge fragment</action>
+</step>
+<step n="4" title="Fixture Architecture">
+  <action>Design fixture/factory patterns per knowledge fragments</action>
+  <action>Pure functions first, framework fixtures as wrappers</action>
+</step>
+<step n="5" title="Generate Output">
+  <action>Generate test framework setup document with config, folder structure, fixture patterns, and instructions for running tests</action>
+  <template-output file="{test_artifacts}/test-framework-setup.md" />
+</step>
+</workflow>

package/_gaia/testing/workflows/test-framework/workflow.yaml

@@ -0,0 +1,11 @@
+name: test-framework
+description: 'Initialize test framework with appropriate tooling'
+module: testing
+agent: test-architect
+config_resolved: "{installed_path}/.resolved/test-framework.yaml"
+config_source: "{project-root}/_gaia/testing/config.yaml"
+installed_path: "{project-root}/_gaia/testing/workflows/test-framework"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+output:
+  primary: "{test_artifacts}/test-framework-setup.md"

package/_gaia/testing/workflows/test-review/checklist.md

@@ -0,0 +1,9 @@
+# Test Review Checklist
+- [ ] Target test files loaded and analyzed
+- [ ] Determinism verified (no timing dependencies)
+- [ ] Test isolation confirmed (no shared mutable state)
+- [ ] Naming conventions assessed
+- [ ] Coverage gaps identified (untested paths, edge cases, boundary conditions)
+- [ ] Critical path coverage assessed (high-risk functions have happy/error/boundary tests)
+- [ ] Flaky test candidates identified
+- [ ] Actionable recommendations provided

package/_gaia/testing/workflows/test-review/instructions.xml

@@ -0,0 +1,51 @@
+<workflow name="test-review">
+<critical>
+  <mandate>Check for flaky test patterns — they are critical technical debt</mandate>
+  <mandate>Story must be in review status before test review</mandate>
+  <mandate>Output must include machine-readable PASSED or FAILED verdict</mandate>
+  <mandate>When reading or running application source code, use {project-path} as the base directory — NOT {project-root}. {project-path} is resolved by the engine from global.yaml.</mandate>
+</critical>
+<step n="1" title="Load Story and Tests">
+  <action>Resolve story file: search for {story_key}-*.md in {implementation_artifacts}/ using glob pattern to match the full filename ({story_key}-{title_slug}.md)</action>
+  <action>Read story file, identify files changed</action>
+  <action>Read test files for the target area</action>
+</step>
+<step n="2" title="Status Gate">
+  <action>Verify story is in 'review' status</action>
+  <check if="status != review">HALT: Story must be in review status before test review</check>
+</step>
+<step n="3" title="Quality Assessment">
+  <action>Check: determinism (no timing/order dependencies), isolation (no shared mutable state), naming (descriptive test names reflecting behavior), assertions (meaningful assertions, not just "no error")</action>
+  <action>Coverage gap analysis: identify untested code paths — error handling branches, boundary conditions, edge cases, null/empty inputs, concurrent access paths, and failure/retry scenarios</action>
+  <action>Assess critical path coverage: for each high-risk or business-critical function touched by the story, verify that tests exist for the happy path, at least one error path, and boundary values. Flag any critical function with no tests as a blocking gap.</action>
+  <action>List specific coverage gaps: for each gap, note the function/module, the missing scenario (e.g., "no test for timeout handling in fetchUser"), and rate risk as Critical/High/Medium/Low based on likelihood and impact of the untested path failing in production</action>
+</step>
+<step n="4" title="Flakiness Analysis">
+  <action>Identify potentially flaky tests: timing, state, network dependencies</action>
+</step>
+<step n="5" title="Verdict">
+  <action>If no critical quality issues or flaky tests found: verdict is PASSED</action>
+  <action>If critical quality issues or flaky tests found: verdict is FAILED — list blocking findings</action>
+</step>
+<step n="6" title="Generate Report">
+  <action>Generate test review report with quality assessment and flakiness findings</action>
+  <template-output file="{test_artifacts}/{story_key}-test-review.md">
+    Generate test review report with:
+    - Quality assessment (determinism, isolation, naming, assertions)
+    - Coverage Gaps section: table of untested paths (Function/Module | Missing Scenario | Risk Rating). Include untested error handling, boundary conditions, and edge cases.
+    - Critical Path Coverage: list each critical function and whether it has happy-path, error-path, and boundary tests
+    - Flakiness findings
+    - Machine-readable verdict (PASSED/FAILED)
+  </template-output>
+</step>
+<step n="7" title="Update Review Gate and Transition">
+  <action>Read story file, locate Review Gate table</action>
+  <action>If PASSED: update Test Review row status to PASSED, link report file</action>
+  <action>If FAILED: update Test Review row status to FAILED, link report file. Do NOT change story status — the review-gate-check protocol or run-all-reviews orchestrator handles status transitions.</action>
+  <template-output file="{implementation_artifacts}/{story_key}-*.md">
+    Update story file Review Gate table with test review result and report link.
+  </template-output>
+  <action>Inform user: "Note: sprint-status.yaml may now be out of sync. Run /gaia-sprint-status to reconcile."</action>
+  <invoke-protocol name="review-gate-check" file="{project-root}/_gaia/core/protocols/review-gate-check.xml" />
+</step>
+</workflow>

package/_gaia/testing/workflows/test-review/workflow.yaml

@@ -0,0 +1,11 @@
+name: test-review
+description: 'Review test quality using best practices validation'
+module: testing
+agent: test-architect
+config_resolved: "{installed_path}/.resolved/test-review.yaml"
+config_source: "{project-root}/_gaia/testing/config.yaml"
+installed_path: "{project-root}/_gaia/testing/workflows/test-review"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+output:
+  primary: "{test_artifacts}/test-review.md"

package/_gaia/testing/workflows/traceability/checklist.md

@@ -0,0 +1,6 @@
+# Traceability Checklist
+- [ ] All requirements loaded (PRD, stories, AC)
+- [ ] Existing tests inventoried
+- [ ] Requirement-to-test matrix built
+- [ ] Coverage gaps identified and prioritized
+- [ ] Gap closure recommendations provided

package/_gaia/testing/workflows/traceability/instructions.xml

@@ -0,0 +1,49 @@
+<workflow name="traceability">
+<critical>
+  <mandate>Map every requirement to at least one test</mandate>
+  <mandate>Identify requirements without test coverage as gaps</mandate>
+  <mandate>Matrix rows MUST be PRD requirements (FR-001…FR-N, NFR-001…NFR-N), NOT story acceptance criteria. Stories are an intermediate mapping between requirements and tests, not the primary dimension.</mandate>
+</critical>
+<step n="1" title="Load Requirements">
+  <action>Load {planning_artifacts}/prd.md — extract ALL functional requirements (FR-001 through FR-N) and non-functional requirements (NFR-001 through NFR-N) as the primary requirement inventory. These are the matrix rows.</action>
+  <check>If prd.md does not exist or cannot be loaded: HALT — "PRD not found at {planning_artifacts}/prd.md. Run /gaia-create-prd first. The traceability matrix requires PRD requirements as its primary dimension."</check>
+  <action>Load {planning_artifacts}/epics-and-stories.md — for each story, identify which FR/NFR it implements. Build a mapping: FR/NFR → Story(s) → Story ACs.</action>
+  <action>Load {test_artifacts}/test-plan.md if it exists — extract planned test IDs and their categories (Unit, Integration, E2E, Manual, Performance, Security, Accessibility).</action>
+</step>
+<step n="2" title="Load Test Inventory">
+  <action>Scan existing test files and test descriptions from test-plan.md</action>
+  <action>For each test, record: test ID, test type (Unit/Integration/E2E/Manual/Performance/Security/Accessibility), implementation status (planned/implemented), and file path if implemented</action>
+</step>
+<step n="3" title="Build Matrix">
+  <action>Build the Functional Requirements matrix section:
+    Rows: FR-001 through FR-N (from PRD)
+    Columns: FR ID | Description | Story(s) | Unit | Integration | E2E | Manual | Coverage %
+    For each FR, map to its implementing story(s) via the FR→Story mapping from Step 1, then map stories to their planned/implemented tests.</action>
+  <action>Build the Non-Functional Requirements matrix section:
+    Rows: NFR-001 through NFR-N (from PRD)
+    Columns: NFR ID | Description | Category | Target | Test(s) | Status
+    Categories: Performance, Security, Accessibility, Scalability, Reliability, etc.
+    Map each NFR to its non-functional test(s) — these may not have story intermediaries.</action>
+  <action>Build the Story→Test detail section as a supplementary view:
+    For each story with ACs, list the specific test IDs covering each AC.
+    This section supports the primary FR/NFR matrix but is NOT the primary dimension.</action>
+</step>
+<step n="4" title="Gap Analysis">
+  <action>Identify FR/NFR requirements with no mapped story — flag as "No implementing story" gap</action>
+  <action>Identify FR/NFR requirements with stories but no mapped tests — flag as "No test coverage" gap</action>
+  <action>Identify tests with no requirement mapping — flag as "Orphan test" warning</action>
+  <action>For each story tagged Risk: HIGH — check if {test_artifacts}/atdd-{story_key}.md exists. If missing, flag as "HIGH-RISK STORY WITHOUT ATDD — run /gaia-atdd before /gaia-dev-story" gap. This is a blocking gap.</action>
+  <action>Prioritize gaps by risk level (High-risk FR/NFRs without coverage are blocking)</action>
+  <action>Calculate implementation rate: count implemented tests vs total planned tests. Record as: Total planned: N, Implemented: M ({percentage}%)</action>
+</step>
+<step n="5" title="Generate Matrix">
+  <action>Generate traceability matrix with:
+    1. FR Requirements → Test mapping table
+    2. NFR Requirements → Test mapping table
+    3. Story AC → Test detail (supplementary)
+    4. Gap analysis summary
+    5. Coverage statistics
+    6. Implementation-readiness gate decision: if all High-risk FR/NFRs have at least one planned test AND implementation rate > 50%, declare PASS. If any High-risk FR/NFR has zero test coverage, declare BLOCKED. Otherwise declare CONDITIONAL.</action>
+  <template-output file="{test_artifacts}/traceability-matrix.md" />
+</step>
+</workflow>

package/_gaia/testing/workflows/traceability/workflow.yaml

@@ -0,0 +1,21 @@
+name: traceability
+description: 'Generate traceability matrix and quality gate decision'
+module: testing
+agent: test-architect
+config_resolved: "{installed_path}/.resolved/traceability.yaml"
+config_source: "{project-root}/_gaia/testing/config.yaml"
+installed_path: "{project-root}/_gaia/testing/workflows/traceability"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+input_file_patterns:
+  prd:
+    whole: "{planning_artifacts}/prd.md"
+    load_strategy: "FULL_LOAD"
+  epics_and_stories:
+    whole: "{planning_artifacts}/epics-and-stories.md"
+    load_strategy: "FULL_LOAD"
+  test_plan:
+    whole: "{test_artifacts}/test-plan.md"
+    load_strategy: "FULL_LOAD"
+output:
+  primary: "{test_artifacts}/traceability-matrix.md"

package/bin/gaia-framework.js

@@ -6,10 +6,40 @@
 // ─────────────────────────────────────────────────────────────────────────────
 
 const { execSync, execFileSync } = require("child_process");
-const { mkdtempSync, rmSync, existsSync, readFileSync, realpathSync } = require("fs");
+const { mkdtempSync, rmSync, existsSync, readFileSync } = require("fs");
 const { join } = require("path");
 const { tmpdir } = require("os");
 
+// ─── Node.js Version Guard (E7-S2) ─────────────────────────────────────────
+
+const MIN_NODE_MAJOR = 20;
+
+function stripPrefix(version) {
+  return (version || "").replace(/^v/, "");
+}
+
+function checkNodeVersion(version) {
+  const major = parseInt(stripPrefix(version).split(".")[0], 10);
+  return major >= MIN_NODE_MAJOR;
+}
+
+function getNodeVersionWarning(version) {
+  const current = stripPrefix(version);
+  return (
+    `\x1b[31m✖\x1b[0m  Node.js ${current} is not supported.\n` +
+    `   GAIA Framework requires Node.js >= ${MIN_NODE_MAJOR}.\n` +
+    `   Download the latest version: https://nodejs.org/en/download\n` +
+    `   Current: ${current} | Required: >= ${MIN_NODE_MAJOR}`
+  );
+}
+
+if (require.main === module && !checkNodeVersion(process.version)) {
+  console.error(getNodeVersionWarning(process.version));
+  process.exit(1);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
 const REPO_URL = "https://github.com/jlouage/Gaia-framework.git";
 const SCRIPT_NAME = "gaia-install.sh";
 const IS_WINDOWS = process.platform === "win32";
@@ -35,9 +65,9 @@ function findBash() {
 
   // 1. Try Git for Windows FIRST (preferred — simpler path mapping)
   const gitBashPaths = [
-    path.join(process.env.ProgramFiles || "C:\\Program Files", "Git", "bin", "bash.exe"),
-    path.join(process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)", "Git", "bin", "bash.exe"),
-    path.join(process.env.LOCALAPPDATA || "", "Programs", "Git", "bin", "bash.exe"),
+    join(process.env.ProgramFiles || "C:\\Program Files", "Git", "bin", "bash.exe"),
+    join(process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)", "Git", "bin", "bash.exe"),
+    join(process.env.LOCALAPPDATA || "", "Programs", "Git", "bin", "bash.exe"),
   ];
 
   for (const p of gitBashPaths) {
@@ -52,7 +82,10 @@ function findBash() {
     execSync("bash --version", { stdio: "ignore" });
     // Detect WSL vs Git Bash by checking uname
     try {
-      const uname = execSync('bash -c "uname -r"', { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }).trim();
+      const uname = execSync('bash -c "uname -r"', {
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "ignore"],
+      }).trim();
       if (/microsoft|wsl/i.test(uname)) {
         bashType = "wsl";
       } else {
@@ -61,7 +94,10 @@ function findBash() {
     } catch {
       // Can't detect — try MSYSTEM env which Git Bash sets
       try {
-        const msys = execSync('bash -c "echo $MSYSTEM"', { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }).trim();
+        const msys = execSync('bash -c "echo $MSYSTEM"', {
+          encoding: "utf8",
+          stdio: ["pipe", "pipe", "ignore"],
+        }).trim();
         bashType = msys ? "gitbash" : "wsl";
       } catch {
         bashType = "wsl"; // Assume WSL if detection fails — safer path mapping
@@ -96,10 +132,7 @@ function ensureGit() {
   try {
     execSync("git --version", { stdio: "ignore" });
   } catch {
-    fail(
-      "git is required but was not found.\n" +
-        "   Install git: https://git-scm.com/downloads"
-    );
+    fail("git is required but was not found.\n" + "   Install git: https://git-scm.com/downloads");
   }
 }
 
@@ -144,12 +177,9 @@ Examples:
 
 function main(deps) {
   // Dependency injection for testability — defaults to real modules
-  const _exec = deps && deps.execSync || execSync;
-  const _execFile = deps && deps.execFileSync || execFileSync;
-  const _mkdtemp = deps && deps.mkdtempSync || mkdtempSync;
-  const _exists = deps && deps.existsSync || existsSync;
-  const _join = deps && deps.join || join;
-  const _tmpdir = deps && deps.tmpdir || tmpdir;
+  const _exec = (deps && deps.execSync) || execSync;
+  const _exists = (deps && deps.existsSync) || existsSync;
+  const _join = (deps && deps.join) || join;
 
   const args = process.argv.slice(2);
 
@@ -191,8 +221,14 @@ function main(deps) {
 
   // Register cleanup for all exit scenarios
   process.on("exit", cleanup);
-  process.on("SIGINT", () => { cleanup(); process.exit(130); });
-  process.on("SIGTERM", () => { cleanup(); process.exit(143); });
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(130);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(143);
+  });
 
   info("Cloning GAIA framework from GitHub...");
 
@@ -233,7 +269,9 @@ function main(deps) {
 
   try {
     // Convert all passthrough args that look like paths (contain backslash or drive letter)
-    const posixArgs = passthrough.map(a => IS_WINDOWS && /[\\:]/.test(a) && !a.startsWith("--") ? toPosixPath(a) : a);
+    const posixArgs = passthrough.map((a) =>
+      IS_WINDOWS && /[\\:]/.test(a) && !a.startsWith("--") ? toPosixPath(a) : a
+    );
     const posixScript = toPosixPath(scriptPath);
 
     // Debug: on Windows, log the resolved paths if --verbose is passed
@@ -257,4 +295,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { findBash, ensureGit, showUsage, fail, info, cleanup, readPackageVersion, main };
+module.exports = { checkNodeVersion, getNodeVersionWarning, findBash, ensureGit, showUsage, fail, info, cleanup, readPackageVersion, main };

package/gaia-install.sh

@@ -6,7 +6,7 @@ set -euo pipefail
 # Installs, updates, validates, and reports on GAIA installations.
 # ─────────────────────────────────────────────────────────────────────────────
 
-readonly VERSION="1.58.0"
+readonly VERSION="1.59.0"
 readonly GITHUB_REPO="https://github.com/jlouage/Gaia-framework.git"
 readonly MANIFEST_REL="_gaia/_config/manifest.yaml"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-framework",
-  "version": "1.58.0",
+  "version": "1.59.0",
   "description": "GAIA — Generative Agile Intelligence Architecture installer",
   "bin": {
     "gaia-framework": "./bin/gaia-framework.js"
@@ -15,7 +15,11 @@
     "test:shell": "node -e \"if(process.platform==='win32'){console.log('BATS tests skipped on Windows');process.exit(0)}\" && bats test/shell/",
     "test:all": "vitest run && node -e \"if(process.platform==='win32'){console.log('BATS tests skipped on Windows');process.exit(0)}\" && bats test/shell/",
     "test:tier2": "vitest run --config vitest.config.tier2.js",
-    "fixtures:check": "node test/fixtures/sync-check.js"
+    "fixtures:check": "node test/fixtures/sync-check.js",
+    "lint": "eslint bin/**/*.js test/**/*.js",
+    "lint:fix": "eslint --fix bin/**/*.js test/**/*.js",
+    "format:check": "prettier --check \"bin/**/*.js\" \"test/**/*.js\"",
+    "format": "prettier --write \"bin/**/*.js\" \"test/**/*.js\""
   },
   "keywords": [
     "gaia",
@@ -32,17 +36,27 @@
   },
   "license": "AGPL-3.0",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "files": [
     "bin/",
-    "gaia-install.sh"
+    "gaia-install.sh",
+    "_gaia/",
+    ".claude/",
+    "CLAUDE.md",
+    "README.md",
+    "LICENSE"
   ],
   "devDependencies": {
-    "vitest": "^3.1.0",
+    "@eslint/js": "^9.39.4",
     "@vitest/coverage-v8": "^3.1.0",
-    "js-yaml": "^4.1.0",
+    "csv-parse": "^5.6.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
     "fast-xml-parser": "^5.2.0",
-    "csv-parse": "^5.6.0"
+    "globals": "^17.4.0",
+    "js-yaml": "^4.1.0",
+    "prettier": "^3.8.1",
+    "vitest": "^3.1.0"
   }
 }