gaia-framework 1.65.1 → 1.66.0

package/_gaia/lifecycle/workflows/anytime/brownfield-onboarding/checklist.md

@@ -18,6 +18,18 @@ validation-target: 'Brownfield onboarding output'
 - [ ] Event catalog subagent completed (if has_events) — {planning_artifacts}/event-catalog.md exists
 - [ ] All API docs use Swagger/OpenAPI format
 - [ ] All diagrams use Mermaid syntax
+## Step 2.5: Deep Analysis Subagents
+- [ ] Config contradiction scanner subagent completed — {planning_artifacts}/brownfield-scan-config-contradiction.md exists
+- [ ] Scanner detected all supported config file types (.yaml, .yml, .json, .env, .toml, .ini, .properties, .xml)
+- [ ] Stack-aware patterns applied based on {tech_stack}
+- [ ] Gap entries conform to standardized schema (gap-entry-schema.md)
+- [ ] Budget control enforced — max ~70 gap entries per scanner
+## Step 2.75: Test Execution During Discovery
+- [ ] Test execution subagent completed — {planning_artifacts}/brownfield-scan-test-execution.md exists (or warning logged if no test suite)
+- [ ] Test runner auto-detection ran for supported runners (npm, pytest, Maven, Gradle, Go, Flutter)
+- [ ] Test failures converted to gap entries conforming to E11-S1 schema
+- [ ] Infrastructure errors distinguished from test failures
+- [ ] Test execution non-blocking — failures did not halt workflow
 ## Step 3: NFR Assessment & Performance Test Plan
 - [ ] NFR assessment subagent completed — {test_artifacts}/nfr-assessment.md exists
 - [ ] NFR baseline summary table has real measured values (not placeholders)

package/_gaia/lifecycle/workflows/anytime/brownfield-onboarding/instructions.xml

@@ -17,9 +17,23 @@
   <action>Frontend Detection: scan for React, Angular, Vue, Flutter, SwiftUI, UI frameworks, CSS/styling. Set {has_frontend} flag (true/false)</action>
   <action>Testing infrastructure: identify test framework, coverage config, test count, test patterns</action>
   <action>CI/CD: identify GitHub Actions, Jenkins, Docker, Terraform, or other pipeline files</action>
-  <action>Generate brownfield assessment: read {installed_path}/../../templates/brownfield-assessment-template.md — capture component inventory, technical debt, migration constraints, coexistence strategy, and adoption path. Output to {planning_artifacts}/brownfield-assessment.md</action>
+  <action>Project Type Detection (ADR-022 Template Discriminator Pattern): scan {project-path} for infrastructure file patterns across 6 marker categories to determine {project_type}. Each category is independently detected:
+    — Terraform: *.tf, *.tfvars
+    — Docker: Dockerfile, docker-compose.yml
+    — Helm: helm/, Chart.yaml, values.yaml
+    — Kubernetes: k8s/, kustomization.yaml
+    — Pulumi: Pulumi.yaml
+    — CloudFormation: cloudformation*.yaml
+  If ANY infrastructure marker is detected, set {has_infra} = true.</action>
+  <action>Application code detection: scan for framework imports (Express, Spring Boot, Django, FastAPI, Angular, React, Next.js, NestJS, Flask, Gin, Fiber) in source files (*.ts, *.js, *.java, *.py, *.go, *.dart). If framework imports found, set {has_app_code} = true.</action>
+  <action>Classification decision tree — set {project_type}:
+    — If {has_infra} = true AND {has_app_code} = true → {project_type} = platform (infrastructure and application code both present)
+    — If {has_infra} = true AND {has_app_code} = false → {project_type} = infrastructure
+    — If {has_infra} = false → {project_type} = application (default — standard software project)
+  The {project_type} variable is set here in Step 1 so it is available before E11 scanners execute in Step 2.5.</action>
+  <action>Generate brownfield assessment: read {installed_path}/../../templates/brownfield-assessment-template.md — capture component inventory, technical debt, migration constraints, coexistence strategy, and adoption path. Include {project_type} in the assessment output. Output to {planning_artifacts}/brownfield-assessment.md</action>
   <template-output file="{planning_artifacts}/project-documentation.md">
-    Generate enhanced project documentation following the project documentation conventions. Include all standard sections plus: detected capability flags (has_apis, has_events, has_external_deps, has_frontend), testing infrastructure summary, and CI/CD pipeline summary.
+    Generate enhanced project documentation following the project documentation conventions. Include all standard sections plus: detected capability flags (has_apis, has_events, has_external_deps, has_frontend), {project_type}, testing infrastructure summary, and CI/CD pipeline summary.
   </template-output>
 </step>
 
@@ -36,14 +50,154 @@
   </template-output>
 </step>
 
+<step n="2.5" title="Deep Analysis Subagents (Infra-Aware)">
+  <action>Spawn deep analysis scan subagents in parallel using the Agent tool with multiple calls in a single message. These run alongside the Step 2 documentation subagents to detect gaps that structural analysis misses. Each scan subagent receives {tech_stack} (from Step 1), {project-path}, and {project_type} as context variables. When {project_type} is `infrastructure` or `platform`, infra-specific detection patterns are applied alongside application patterns. When {project_type} is `application`, only application patterns are applied.</action>
+
+  <action>Spawn subagent — Config Contradiction Scanner (infra-aware): "Read the config contradiction scan prompt template at {project-root}/_gaia/lifecycle/knowledge/brownfield/config-contradiction-scan.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. If project_type is infrastructure or platform: also apply infra-specific config contradiction patterns for terraform.tfvars, values.yaml, and kustomize overlays as specified in the prompt template. Output to {planning_artifacts}/brownfield-scan-config-contradiction.md"</action>
+
+  <action>Spawn subagent — Dead Code &amp; Dead State Scanner: "Read the dead code scan prompt template at {project-root}/_gaia/lifecycle/knowledge/brownfield/dead-code-scan.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. Output to {planning_artifacts}/brownfield-scan-dead-code.md"</action>
+
+  <action>Spawn subagent — Hard-Coded Logic Detector (infra-aware): "Read the hard-coded logic scan prompt template at {project-root}/_gaia/lifecycle/templates/brownfield-scan-hardcoded-prompt.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. If project_type is infrastructure or platform: also detect hard-coded IPs, magic ports, embedded secrets/AMI IDs, and hard-coded resource limits in IaC files as specified in the prompt template. Output to {planning_artifacts}/brownfield-scan-hardcoded.md"</action>
+
+  <action>Spawn subagent — Security Endpoint Audit (infra-aware): "Read the security scan prompt template at {project-root}/_gaia/lifecycle/templates/brownfield-scan-security-prompt.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. If project_type is infrastructure or platform: also detect exposed ports in k8s manifests, permissive ingress rules, overly broad RBAC bindings, and missing NetworkPolicy as specified in the prompt template. Output to {planning_artifacts}/brownfield-scan-security.md"</action>
+
+  <action>Spawn subagent — Runtime Behavior Inventory (infra-aware): "Read the runtime behavior scan prompt template at {project-root}/_gaia/lifecycle/templates/brownfield-scan-runtime-behavior-prompt.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. If project_type is infrastructure or platform: also catalog CronJobs, DaemonSets, init containers, sidecar patterns, and health probes as specified in the prompt template. Output to {planning_artifacts}/brownfield-scan-runtime-behavior.md"</action>
+
+  <action>Spawn subagent — Documentation-Code Mismatch Scanner: "Read the doc-vs-code scan prompt template at {project-root}/_gaia/lifecycle/templates/brownfield-scan-doc-code-prompt.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. Output to {planning_artifacts}/brownfield-scan-doc-code.md"</action>
+
+  <action>Spawn subagent — Integration Seam Analyzer (infra-aware): "Read the integration seam scan prompt template at {project-root}/_gaia/lifecycle/templates/brownfield-scan-integration-seam-prompt.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. If project_type is infrastructure or platform: also map service mesh topology, ingress/egress routes, and cross-namespace dependencies as specified in the prompt template. Output to {planning_artifacts}/brownfield-scan-integration-seam.md"</action>
+
+  <action>Wait for all deep analysis subagents to complete. Verify output files exist at {planning_artifacts}/: brownfield-scan-config-contradiction.md, brownfield-scan-dead-code.md, brownfield-scan-hardcoded.md, brownfield-scan-security.md, brownfield-scan-runtime-behavior.md, brownfield-scan-doc-code.md, and brownfield-scan-integration-seam.md.</action>
+  <action>If any subagent failed to write its output file: log a warning and continue — individual scan failures should not block the overall brownfield workflow.</action>
+
+  <!-- Gap-to-Requirement Mapping Reference (E12-S6, ADR-022 §10.16.5)
+       When {project_type} is infrastructure or platform, infra gap categories
+       map to infra PRD sections as follows:
+
+       | Gap Category       | Infra PRD Section          |
+       |--------------------|----------------------------|
+       | resource-drift     | Resource Specifications    |
+       | config-sprawl      | Environment Strategy & DX  |
+       | secret-exposure    | Security Posture           |
+       | missing-policy     | Verification Strategy      |
+       | environment-skew   | Environment Strategy & DX  |
+
+       Application gap categories map to standard PRD sections:
+       | Gap Category          | PRD Section              |
+       |-----------------------|--------------------------|
+       | functional            | Resource Specifications  |
+       | behavioral            | Operational SLOs         |
+       | security              | Security Posture         |
+       | operational           | Operational Runbooks     |
+       | documentation         | Overview & Scope         |
+       | configuration         | Environment Strategy & DX|
+       | data-integrity        | Resource Specifications  |
+
+       This mapping is consumed by the gap consolidation step (E11-S10/S12)
+       and the PRD generation step (Step 4) to route gap findings to the
+       correct sections of the generated PRD. -->
+</step>
+
+<step n="2.75" title="Test Execution During Discovery">
+  <action>After all Step 2/2.5 parallel scan subagents complete, execute the existing test suite at {project-path} to capture test failures as gap entries. This step is non-blocking — test execution failures must not halt the overall brownfield onboarding workflow.</action>
+  <action>Spawn subagent — Test Execution Scanner: "Read the test execution scan prompt template at {project-root}/_gaia/lifecycle/knowledge/brownfield/test-execution-scan.md. Follow the prompt instructions EXACTLY. Scan the project at {project-path} for test runners. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. Auto-detect test runners (package.json with test script, pytest, Maven, Gradle, Go, Flutter) in priority order. Execute each detected runner with a 5-minute timeout. Parse test output for metrics (total, passing, failing, skipped). Convert failing tests to gap entries with severity mapped by test type (unit=medium, integration=high, e2e=critical). Detect infrastructure errors (ECONNREFUSED, missing env vars) and log as warning gaps instead of test failure gaps. For monorepo/polyglot projects, execute all detected runners sequentially and aggregate results. Truncate output per NFR-024 token budget if needed. If no test suite is detected, log an info-level gap entry GAP-TEST-INFO-001. Output to {planning_artifacts}/brownfield-scan-test-execution.md"</action>
+  <action>When subagent returns: verify output file exists at {planning_artifacts}/brownfield-scan-test-execution.md.</action>
+  <action>If the subagent failed to write its output file: log a warning and continue — test execution scan failures should not block the overall brownfield workflow.</action>
+</step>
+
 <step n="3" title="NFR Assessment &amp; Performance Test Plan">
   <action>Spawn a subagent — "Analyze the codebase at {project-path} for non-functional requirements. Read {installed_path}/../../templates/nfr-assessment-template.md for the output format. Assess: code quality (linting, complexity, duplication), security posture (dependency vulnerabilities, secrets handling, auth quality — load security-basics skill section vulnerability-scanning if needed), performance (bundle size if frontend, query patterns, caching, resource management), accessibility (ARIA, semantic HTML, keyboard nav if frontend), test coverage (framework, count, coverage %, untested areas, quality), CI/CD (build pipeline, deploy strategy, environments, IaC). Create NFR Baseline Summary Table with measured values (not placeholders). Output to {test_artifacts}/nfr-assessment.md. Then create a performance test plan: load {project-root}/_gaia/testing/knowledge/performance/k6-patterns.md for load testing patterns. If {has_frontend}: also load {project-root}/_gaia/testing/knowledge/performance/lighthouse-ci.md. Define performance budgets (P50/P95/P99) based on NFR baselines, load test scenarios (gradual, spike, soak), backend profiling targets (slow queries, N+1, connection pools), CI performance gates. If {has_frontend}: define Core Web Vitals targets (LCP under 2.5s, INP under 200ms, CLS under 0.1). Output to {test_artifacts}/performance-test-plan-{date}.md"</action>
   <action>When subagent returns: verify both {test_artifacts}/nfr-assessment.md and {test_artifacts}/performance-test-plan-{date}.md exist. If the subagent failed to write files, the orchestrator MUST write them to {test_artifacts}/ as declared in workflow.yaml output.artifacts — do NOT fall back to {planning_artifacts}/.</action>
 </step>
 
+<step n="3.5" title="Gap Consolidation &amp; Deduplication">
+  <action>Spawn a subagent using the Agent tool with this prompt:
+
+  "You are the Gap Consolidation subagent. Your task is to load all scan results, deduplicate them, rank them, and produce a single consolidated output file.
+
+  **Context:**
+  - Planning artifacts directory: {planning_artifacts}/
+  - Test artifacts directory: {test_artifacts}/
+  - Gap schema reference: {installed_path}/../../templates/gap-entry-schema.md
+  - Tech stack: {tech_stack}
+
+  **Step 1 — Load all scan outputs:**
+  Load gap entries from ALL of the following sources. For each file, if it exists, parse YAML gap entries matching the schema from gap-entry-schema.md. If a file is empty or missing, log a warning noting which scanner produced no results and continue processing the remaining files without error.
+
+  Deep analysis scan outputs (7 files):
+  - {planning_artifacts}/brownfield-scan-config-contradiction.md
+  - {planning_artifacts}/brownfield-scan-dead-code.md
+  - {planning_artifacts}/brownfield-scan-hard-coded-logic.md
+  - {planning_artifacts}/brownfield-scan-security-endpoint.md
+  - {planning_artifacts}/brownfield-scan-runtime-behavior.md
+  - {planning_artifacts}/brownfield-scan-doc-code-drift.md
+  - {planning_artifacts}/brownfield-scan-integration-seam.md
+
+  Step 2 documentation subagent outputs:
+  - {planning_artifacts}/api-documentation.md (API gaps)
+  - {planning_artifacts}/event-catalog.md (event/messaging gaps)
+  - {planning_artifacts}/ux-design.md (frontend/UX gaps)
+  - {planning_artifacts}/dependency-map.md (dependency gaps)
+
+  Step 3 test execution results:
+  - {test_artifacts}/nfr-assessment.md (test execution gap findings)
+
+  **Step 2 — Validate entries against schema:**
+  For each parsed gap entry, validate that all required fields are present: id, category, severity, title, description (or evidence), evidence_file, evidence_line, recommendation. Entries missing any required field are logged as warnings (noting the source file and which field is missing) and skipped from consolidation rather than causing a failure.
+
+  **Step 3 — Deduplicate:**
+  Group gap entries by evidence_file + evidence_line (exact match on both fields). For each group of duplicates:
+  a. Retain the entry with the highest severity (critical > high > medium > low)
+  b. Merge recommendations from all duplicate entries into the retained entry
+  c. Add a merged_from field listing all original gap IDs that were merged
+  d. If duplicates have different categories, retain the primary category from the highest-severity entry and note the alternate category in the description
+
+  **Step 4 — Rank:**
+  Sort the deduplicated gaps by:
+  1. severity DESC (critical first, then high, medium, low)
+  2. confidence DESC (high first, then medium, low)
+  3. category alphabetical within each severity+confidence tier
+  Assign final sequential numbering to the ranked list.
+
+  **Step 5 — Budget check:**
+  Estimate the token count of the output (~100 tokens per gap entry). If the estimated total exceeds the 40K token budget, truncate low-severity and info entries with a count summary: 'N additional low/info gaps omitted for budget'. Ensure the output stays within budget.
+
+  **Step 6 — Generate consolidated output:**
+  Write consolidated-gaps.md to {planning_artifacts}/ using the consolidated output format from gap-entry-schema.md. Include summary statistics at the top:
+  - Total raw gaps (pre-dedup count)
+  - Duplicates removed
+  - Final unique count
+  - Breakdown by category (all categories found)
+  - Breakdown by severity (critical, high, medium, low)
+  - Per-scanner source counts
+
+  Output to {planning_artifacts}/consolidated-gaps.md"
+  </action>
+  <action>When subagent returns: verify {planning_artifacts}/consolidated-gaps.md exists. If the subagent failed to write the file, log error and halt.</action>
+  <template-output file="{planning_artifacts}/consolidated-gaps.md">
+    Consolidated gap analysis with deduplicated, ranked gaps in standardized schema format. Includes summary statistics header.
+  </template-output>
+</step>
+
 <step n="4" title="Create PRD for Gaps">
-  <action>Read the PRD template from {installed_path}/../../templates/prd-template.md</action>
+  <action>Select PRD template based on {project_type} (set by Step 1 discovery). Template selection is a simple lookup — no template inheritance or composition at runtime:
+
+  | project_type     | Template File              | Requirement ID Scheme                        |
+  |------------------|----------------------------|----------------------------------------------|
+  | application      | prd-template.md            | FR-###, NFR-###                              |
+  | infrastructure   | infra-prd-template.md      | IR-###, OR-###, SR-###                       |
+  | platform         | platform-prd-template.md   | FR-###, NFR-### and IR-###, OR-###, SR-###   |
+
+  Resolve template path: {installed_path}/../../templates/{selected_template}.
+  Verify the selected template file exists before proceeding. If the template file is missing, HALT with: "Template {selected_template} not found at {installed_path}/../../templates/. Ensure E12-S2 (infra) or E12-S3 (platform) templates are installed."
+  If {project_type} is not set or unrecognized, default to application (prd-template.md) for backward compatibility.</action>
+  <action>Read the selected PRD template from {installed_path}/../../templates/{selected_template}</action>
+  <action>Set requirement ID scheme based on {project_type}:
+  — If application: use FR-### for functional requirements and NFR-### for non-functional requirements (existing behavior, backward compatible)
+  — If infrastructure: use IR-### for infrastructure requirements, OR-### for operational requirements, and SR-### for security requirements exclusively. Do NOT use FR/NFR prefixes.
+  — If platform: use BOTH ID scheme families — FR-###/NFR-### for application-layer requirements and IR-###/OR-###/SR-### for infrastructure-layer requirements. All requirement IDs are globally unique within the project — the prefix disambiguates (e.g., FR-001 and IR-001 are distinct, no collision).</action>
   <action>Read upstream artifacts to inform gap analysis:</action>
+  <action>— consolidated-gaps.md → primary input: deduplicated, ranked, and code-verified gap list from Steps 3.5 and 5.5. If a '## Verification Corrections for PRD' section exists, use it to correct factual errors from contradicted claims.</action>
   <action>— nfr-assessment.md → NFR section gets real "Current Baseline" and "Target" columns</action>
   <action>— api-documentation.md (if exists) → extract API gaps (undocumented endpoints, missing validation)</action>
   <action>— event-catalog.md (if exists) → extract messaging gaps (missing DLQ, missing schemas)</action>
@@ -73,6 +227,92 @@
   </template-output>
 </step>
 
+<step n="5.5" title="Code-Verified Review">
+  <action>Spawn a subagent using the Agent tool with this prompt:
+
+  "You are the Code-Verified Review subagent. Your task is to verify every factual claim in the consolidated gap entries against the actual codebase, classify each gap, and update the consolidated output.
+
+  **Context:**
+  - Consolidated gaps file: {planning_artifacts}/consolidated-gaps.md
+  - Codebase root: {project-path}
+  - Tech stack: {tech_stack}
+  - Gap schema reference: {installed_path}/../../templates/gap-entry-schema.md
+
+  **Step 1 — Load and parse consolidated-gaps.md:**
+  Read {planning_artifacts}/consolidated-gaps.md. Parse all YAML gap entries matching the standardized gap schema. If the file is empty or contains zero parseable gap entries, output a summary stating '0 gaps to verify' and exit gracefully without error, producing an empty verification report.
+
+  Handle malformed gap entries: if a gap entry is missing required fields (id, category, severity, title, description, evidence_file, recommendation), log a warning noting which field is missing and which entry, skip the entry, and include it in the summary as a skipped entry.
+
+  **Step 2 — Extract verifiable claims from each gap entry:**
+  For each valid gap entry, extract all machine-verifiable claims:
+  a. File existence: extract the `evidence_file` field — this is a relative path from {project-path} that should exist in the codebase.
+  b. Line range validity: extract the `evidence_line` field — this line number must be within the file's total line count.
+  c. Pattern/string presence: extract patterns, strings, or code snippets from the `description` and `recommendation` fields that claim specific code patterns exist in the referenced file.
+  d. Configuration key existence: for gaps in the `configuration` category, extract config key paths claimed to exist in YAML/JSON config files.
+
+  For gap entries with no verifiable claims (purely subjective descriptions with no file/line/pattern references), classify as `unverifiable` with reason 'No machine-verifiable claims'.
+
+  **Step 3 — Verify each claim against the codebase at {project-path}:**
+  Use grep, glob, and read tools for all verification (not shell commands). For each claim:
+
+  a. File existence check: Use glob/read to check if {project-path}/{evidence_file} exists.
+     - If the file does not exist: classify the gap as `contradicted` with reason 'Referenced file not found: {evidence_file}'. Preserve the original gap with downgraded confidence.
+     - If the file is a binary file (detected by extension: .png, .jpg, .gif, .woff, .ttf, .ico, .pdf, .zip, .tar, .gz, .exe, .dll, .so, .dylib): classify as `unverifiable` with reason 'Binary file — cannot verify textual claims'.
+
+  b. Line range validation: Read the file and count total lines. Compare against `evidence_line`.
+     - If evidence_line exceeds the file's total line count: classify as `contradicted` with reason 'Line {evidence_line} exceeds file length ({actual_lines} lines)'. Flag the entry for correction.
+
+  c. Pattern search: Use grep to search for stated patterns in the referenced file. Handle regex special characters safely by escaping them.
+     - If the pattern is found: this claim is confirmed.
+     - If the pattern is not found: this contributes to a `contradicted` classification.
+
+  d. Config key verification: For configuration-category gaps, parse YAML/JSON config files and check for key existence at the stated paths.
+     - If the key exists: claim confirmed.
+     - If the key does not exist: contributes to `contradicted` classification.
+
+  **Step 4 — Apply tristate classification to each gap:**
+  Based on the verification results from Step 3:
+  - **verified**: All verifiable claims in the gap entry are confirmed by evidence in the codebase. Set `verification_status: verified`.
+  - **unverifiable**: Claims cannot be confirmed or denied from code alone (e.g., runtime behavior, subjective assessments, binary files, no verifiable claims). Set `verification_status: unverifiable`.
+  - **contradicted**: Evidence in the codebase directly contradicts one or more claims. Set `verification_status: contradicted`.
+
+  For contradicted gaps:
+  - Downgrade the confidence of the original gap entry.
+  - Attach a `reason` string explaining exactly what was contradicted and what was found instead.
+  - Generate a new gap entry using the standardized gap schema with:
+    - `id`: GAP-VERIFIED-{seq}
+    - `category`: preserved from original gap
+    - `severity`: inherited from original gap
+    - `verified_by: "code-verified"`
+    - `description`: details of the contradiction and the actual state found in codebase
+
+  **Step 5 — Update consolidated-gaps.md:**
+  Write back to {planning_artifacts}/consolidated-gaps.md with the following additions to each gap entry:
+  - `verification_status`: verified | unverifiable | contradicted
+  - `verified_by: "code-verified"`
+  Preserve all existing fields on each entry — do not remove or overwrite original data.
+  Append new gap entries generated from contradicted claims at the end of the file.
+
+  **Step 6 — Generate verification summary:**
+  Output a summary report including:
+  - Total gaps processed
+  - Verified count
+  - Unverifiable count
+  - Contradicted count
+  - New gap entries generated from contradicted claims
+  - Skipped entries (malformed) count
+
+  **Step 7 — Feed contradicted claims back to Step 4:**
+  Contradicted claims must be fed back to Step 4 (PRD generation) for correction. Write the list of contradicted entries and their reasons to a section at the top of consolidated-gaps.md marked '## Verification Corrections for PRD'. This section will be read by Step 4 when the PRD is regenerated to correct factual errors.
+
+  Output to {planning_artifacts}/consolidated-gaps.md"
+  </action>
+  <action>When subagent returns: verify {planning_artifacts}/consolidated-gaps.md has been updated with verification_status fields. If the subagent failed, log error and halt.</action>
+  <template-output file="{planning_artifacts}/consolidated-gaps.md">
+    Code-verified consolidated gaps with verification_status and verified_by fields on each entry. Includes verification summary and corrections section for PRD feedback.
+  </template-output>
+</step>
+
 <step n="6" title="Architecture">
   <action>Architecture is created using the Phase 3 workflow which auto-detects brownfield mode from the PRD "Mode: Brownfield" header set in step 4.</action>
   <action>If {planning_artifacts}/architecture.md already exists: WARN user — "An architecture document already exists. Continuing will overwrite it with the brownfield version. Choose: (a) overwrite, (b) save as architecture-brownfield.md instead." If user chooses (b), instruct the subagent to output to {planning_artifacts}/architecture-brownfield.md.</action>
@@ -92,7 +332,7 @@
   <check if="refresh-ground-truth workflow directory not found">Val ground truth bootstrap skipped — refresh-ground-truth workflow not available. Run /gaia-refresh-ground-truth manually after E8-S9 is implemented. Brownfield onboarding completes successfully.</check>
 
   <action>Invoke /gaia-refresh-ground-truth to scan the filesystem and populate framework inventory facts (workflows, agents, skills, commands) into ground-truth.md</action>
-  <invoke-workflow ref="refresh-ground-truth" mode="yolo" />
+  <invoke-workflow ref="val-refresh-ground-truth" mode="yolo" />
 
   <action>Load brownfield-extraction section of ground-truth-management skill JIT from {project-root}/_gaia/lifecycle/skills/ground-truth-management.md</action>
   <action>Read available brownfield artifacts and extract project-specific facts. For each artifact, check if the file exists before reading — skip missing artifacts without error:

package/_gaia/lifecycle/workflows/anytime/brownfield-onboarding/workflow.yaml

@@ -30,4 +30,5 @@ output:
     - "{planning_artifacts}/prd.md"
     - "{planning_artifacts}/architecture.md"
     - "{planning_artifacts}/epics-and-stories.md"
+    - "{planning_artifacts}/brownfield-scan-test-execution.md"
     - "{planning_artifacts}/brownfield-onboarding.md"

package/bin/gaia-framework.js

@@ -183,6 +183,8 @@ function main(deps) {
   const _join = (deps && deps.join) || join;
   const _mkdtemp = (deps && deps.mkdtempSync) || mkdtempSync;
   const _tmpdir = (deps && deps.tmpdir) || tmpdir;
+  const _isWindows = deps && typeof deps.isWindows === "boolean" ? deps.isWindows : IS_WINDOWS;
+  const _findBash = (deps && deps.findBash) || findBash;
 
   const args = process.argv.slice(2);
 
@@ -212,13 +214,13 @@ function main(deps) {
   tempDir = _mkdtemp(_join(_tmpdir(), "gaia-framework-"));
   // Resolve 8.3 short names to long paths on Windows (e.g., ELIASN~1 → Elias Nasser)
   // Node's realpathSync doesn't expand 8.3 names, so use PowerShell
-  if (IS_WINDOWS) {
+  if (_isWindows) {
     try {
-      const longPath = execSync(
+      const longPath = _exec(
         `powershell -NoProfile -Command "(Get-Item -LiteralPath '${tempDir}').FullName"`,
         { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }
       ).trim();
-      if (longPath && existsSync(longPath)) tempDir = longPath;
+      if (longPath && _exists(longPath)) tempDir = longPath;
     } catch {}
   }
 
@@ -259,7 +261,7 @@ function main(deps) {
   passthrough.splice(1, 0, "--source", toPosixPath(tempDir));
 
   // Locate bash (critical for Windows support)
-  const bashPath = findBash();
+  const bashPath = _findBash();
   if (!bashPath) {
     fail(
       "bash is required but was not found.\n" +
@@ -273,12 +275,12 @@ 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
+      _isWindows && /[\\:]/.test(a) && !a.startsWith("--") ? toPosixPath(a) : a
     );
     const posixScript = toPosixPath(scriptPath);
 
     // Debug: on Windows, log the resolved paths if --verbose is passed
-    if (IS_WINDOWS && args.includes("--verbose")) {
+    if (_isWindows && args.includes("--verbose")) {
       info(`Bash: ${bashPath} (${bashType})`);
       info(`Script (Windows): ${scriptPath}`);
       info(`Script (POSIX): ${posixScript}`);

package/gaia-install.sh

@@ -233,7 +233,7 @@ copy_gaia_files() {
 
   # Fallback: cp -rp (preserves permissions like rsync -a)
   if [[ "$copy_done" == false ]] && command -v cp >/dev/null 2>&1; then
-    if cp -rp "$src/_gaia/" "$dst/_gaia/" 2>/dev/null; then
+    if cp -rp "$src/_gaia/." "$dst/_gaia/" 2>/dev/null; then
       clean_resolved_yaml "$dst/_gaia"
       detail "Copied framework files using cp -rp (rsync unavailable)"
       copy_done=true
@@ -493,16 +493,18 @@ cmd_init() {
     fi
   fi
 
-  # Step 8: Create custom skills directory
-  step "Creating custom skills directory..."
-  if [[ "$OPT_DRY_RUN" == true ]]; then
-    detail "[dry-run] Would create: custom/skills/"
-  else
-    mkdir -p "$TARGET/custom/skills"
-  fi
-  if [[ -f "$source/custom/skills/README.md" ]]; then
-    copy_if_missing "$source/custom/skills/README.md" "$TARGET/custom/skills/README.md"
-  fi
+  # Step 8: Create custom directories (ADR-020: user-owned write targets)
+  step "Creating custom directories..."
+  for cdir in skills templates; do
+    if [[ "$OPT_DRY_RUN" == true ]]; then
+      detail "[dry-run] Would create: custom/$cdir/"
+    else
+      mkdir -p "$TARGET/custom/$cdir"
+    fi
+    if [[ -f "$source/custom/$cdir/README.md" ]]; then
+      copy_if_missing "$source/custom/$cdir/README.md" "$TARGET/custom/$cdir/README.md"
+    fi
+  done
 
   # Step 9: Append GAIA entries to .gitignore
   step "Updating .gitignore..."
@@ -687,15 +689,17 @@ cmd_update() {
     fi
   done
 
-  # Ensure custom skills directory exists (user-owned, never overwritten)
-  if [[ "$OPT_DRY_RUN" == true ]]; then
-    [[ ! -d "$TARGET/custom/skills" ]] && detail "[dry-run] Would create: custom/skills/"
-  else
-    mkdir -p "$TARGET/custom/skills"
-  fi
-  if [[ -f "$source/custom/skills/README.md" ]]; then
-    copy_if_missing "$source/custom/skills/README.md" "$TARGET/custom/skills/README.md"
-  fi
+  # Ensure custom directories exist (user-owned, never overwritten — ADR-020)
+  for cdir in skills templates; do
+    if [[ "$OPT_DRY_RUN" == true ]]; then
+      [[ ! -d "$TARGET/custom/$cdir" ]] && detail "[dry-run] Would create: custom/$cdir/"
+    else
+      mkdir -p "$TARGET/custom/$cdir"
+    fi
+    if [[ -f "$source/custom/$cdir/README.md" ]]; then
+      copy_if_missing "$source/custom/$cdir/README.md" "$TARGET/custom/$cdir/README.md"
+    fi
+  done
 
   # Update slash commands (add new ones, update existing with backup)
   step "Updating slash commands..."
@@ -828,6 +832,10 @@ cmd_validate() {
     [[ -d "$TARGET/docs/$dir" ]]; check "Docs: $dir" $?
   done
 
+  # Custom directories (ADR-020: user-owned write targets)
+  [[ -d "$TARGET/custom/skills" ]]; check "custom/skills/ exists" $?
+  [[ -d "$TARGET/custom/templates" ]]; check "custom/templates/ exists" $?
+
   # Version
   local version
   version="$(extract_yaml_value "$TARGET/_gaia/_config/global.yaml" "framework_version")"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-framework",
-  "version": "1.65.1",
+  "version": "1.66.0",
   "description": "GAIA — Generative Agile Intelligence Architecture installer",
   "bin": {
     "gaia-framework": "./bin/gaia-framework.js"