gaia-framework 1.66.0 → 1.87.0

package/_gaia/lifecycle/workflows/4-implementation/create-stakeholder/workflow.yaml

@@ -0,0 +1,22 @@
+name: create-stakeholder
+description: 'Scaffold a new stakeholder file for Party Mode discussions'
+module: lifecycle
+agent: orchestrator
+config_resolved: "{installed_path}/.resolved/create-stakeholder.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/4-implementation/create-stakeholder"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+quality_gates:
+  pre_start: []
+  post_complete:
+    - check: "stakeholder_file_line_count_valid == true"
+      on_fail: "HALT: Stakeholder file exceeds 100-line limit (FR-164). Edit {project-root}/custom/stakeholders/{slug}.md to reduce content or re-run /gaia-create-stakeholder."
+    - check: "stakeholder_count_in_directory_valid == true"
+      on_fail: "HALT: custom/stakeholders/ has more than 50 files (FR-164). Remove unused stakeholders from {project-root}/custom/stakeholders/ first."
+on_error:
+  missing_file: "ask_user"
+  unresolved_variable: "halt"
+
+output:
+  primary: "{project-root}/custom/stakeholders/{slug}.md"

package/_gaia/lifecycle/workflows/4-implementation/create-story/instructions.xml

@@ -94,6 +94,14 @@
 <step n="6" title="Generate Output">
   <action>Read the story template from the engine-resolved template path. The engine resolves this in Step 1 (Load and Resolve Config): if {project-root}/custom/templates/story-template.md exists and is non-empty, the custom template is used; otherwise it falls back to {project-root}/_gaia/lifecycle/templates/story-template.md. Use whichever path the engine resolved.</action>
   <action>Read sizing_map from {project-root}/_gaia/_config/global.yaml to resolve T-shirt size to story points (S→2, M→5, L→8, XL→13).</action>
+  <action>Detect invocation context to determine origin fields:
+    If invoked from problem-solving routing (E16-S3): set origin="problem-solving" and origin_ref to the path of the Problem Brief or problem-solving checkpoint artifact (e.g., docs/creative-artifacts/problem-solving-YYYY-MM-DD.md).
+    If invoked from triage routing: set origin="triage" and origin_ref to the triage artifact path.
+    If invoked from add-feature routing: set origin="add-feature" and origin_ref to the source artifact path.
+    If invoked from sprint-planning: set origin="sprint-planning" and origin_ref to the sprint plan artifact path.
+    If invoked with explicit origin parameters from caller: use the provided origin and origin_ref values.
+    If invoked normally (no routing context): set origin=null and origin_ref=null (planned work default).
+  </action>
   <action>Populate ALL YAML frontmatter fields from epics-and-stories.md data:
     - key: story key from epics (e.g., E1-S1)
     - title: story title
@@ -110,6 +118,8 @@
     - date: current date
     - author: agent name (e.g., "Nate (Scrum Master)")
     - priority_flag: null (default — set to "next-sprint" by add-feature for high-urgency stories)
+    - origin: workflow origin (null for planned work, "problem-solving" from problem-solving routing, "triage" from triage, "add-feature" from add-feature routing, "sprint-planning" from sprint planning, "manual" for explicit manual creation)
+    - origin_ref: path to source artifact that triggered story creation (null when origin is null)
   </action>
   <template-output file="{implementation_artifacts}/{story_key}-{story_title_slug}.md">
     Generate the story file following the story-template.md structure. The filename must use the story key and slugified title (e.g., E1-S1-user-login.md). Include complete YAML frontmatter with ALL 15 fields populated. Fill all template sections: User Story, Acceptance Criteria, Tasks/Subtasks (linked to AC numbers), Dev Notes, Technical Notes, Dependencies, Test Scenarios, Project Structure Notes, References, Dev Agent Record, and Estimate. IMPORTANT: The body "**Status:**" line MUST match the frontmatter status field exactly. Both must say the same status value.

package/_gaia/lifecycle/workflows/4-implementation/dev-story/instructions.xml

@@ -48,6 +48,16 @@
   </action>
   <action if="mode == REWORK or mode == RESUME">Skip status change — story is already in-progress.</action>
 </step>
+<step n="4b" title="Figma Design Consumption">
+  <action>Check for figma: metadata block in story file YAML frontmatter. Expected fields: file_key (string — Figma file identifier), pages (list of page names to extract from), node_ids (list of specific node IDs), design_version (string — Figma lastModified hash for traceability). Also check ux-design.md for a figma: metadata block.</action>
+  <action if="no figma: metadata block found in story file or ux-design.md">No Figma metadata present — skip all Figma-related actions. Use ux-design.md text as-is with zero behavioral change. Proceed to Step 5.</action>
+  <action if="figma: metadata block is present">JIT-load figma-integration.md tokens and components sections for MCP extraction.</action>
+  <action if="figma: metadata block is present">Check for cached responses in {project-path}/.figma-cache/ using composite cache key {file_key}:{page_id}:{design_version_hash}. If cache hit with valid version hash, use cached data. If cache miss or design version changed since last implementation, proceed with MCP extraction.</action>
+  <action if="figma: metadata block is present and MCP available">Extract design tokens via MCP and write design-tokens.json to {planning_artifacts}/design-system/ in W3C DTCG format. Extract component specs via MCP and write component-specs.yaml to the same directory.</action>
+  <action if="figma: metadata block is present and MCP unreachable">If cached data exists in {project-path}/.figma-cache/ (even with expired TTL), continue with last-known-good files and display [OFFLINE] warning: "Design data loaded from cache — MCP unreachable. Token data may be stale." Do not halt — proceed with stale data.</action>
+  <action if="figma: metadata block is present">Compare design_version in story figma: metadata against the current Figma file version. If the design version has changed since the last implementation run, offer an incremental update: "Design has changed since last implementation (stored: {old_version}, current: {new_version}). Run incremental token update? [y/n]". Record the design_version consumed in the story figma: metadata for traceability.</action>
+  <action if="figma: metadata block is present">JIT-load figma-integration.md export section. Generate stack-specific scaffolded code from intermediate files (design-tokens.json and component-specs.yaml) using the active dev agent's resolution table. Output token files and component scaffolds to {project-path} design system directory.</action>
+</step>
 <step n="5" title="Plan Implementation">
   <action if="mode == REWORK">REWORK MODE — Focus plan on fixing review feedback:
     1. Read the story's Review Gate table — identify which reviews FAILED

package/_gaia/lifecycle/workflows/4-implementation/retrospective/instructions.xml

@@ -108,14 +108,14 @@
 
     3. Apply the improvement: append to or modify the relevant section in custom/skills/{skill-name}.md with comment "<!-- Added from retro-{sprint_id}: {reason} -->".
 
-    4. Register in .customize.yaml: after writing the custom skill file, register it in {project-root}/_gaia/_config/agents/all-dev.customize.yaml so the engine loads from the custom path on subsequent runs.
-       - If all-dev.customize.yaml does not exist: create it with proper YAML structure:
+    4. Register in .customize.yaml: after writing the custom skill file, register it in {project-root}/custom/skills/all-dev.customize.yaml so the engine loads from the custom path on subsequent runs (ADR-020 — customization registries live alongside custom skills in custom/skills/).
+       - If custom/skills/all-dev.customize.yaml does not exist: create it with proper YAML structure:
          ```yaml
          skill_overrides:
            {skill-name}:
              source: "custom/skills/{skill-name}.md"
          ```
-       - If all-dev.customize.yaml already exists: read current content, check if a skill_overrides entry for this skill already exists. If it does not exist, append the new entry under skill_overrides. Preserve all existing entries — only add the new one. If it already exists (duplicate), skip registration to prevent duplicate entries.
+       - If custom/skills/all-dev.customize.yaml already exists: read current content, check if a skill_overrides entry for this skill already exists. If it does not exist, append the new entry under skill_overrides. Preserve all existing entries — only add the new one. If it already exists (duplicate), skip registration to prevent duplicate entries.
   </action>
   <action>If no skill improvements identified, state: "No skill improvements identified this sprint."</action>
 </step>

package/_gaia/lifecycle/workflows/4-implementation/validate-story/instructions.xml

@@ -45,6 +45,17 @@
       (file paths, component references, API endpoints, dependency versions).
       Verify against filesystem and ground truth (if available).
       Classify findings as CRITICAL (broken reference), WARNING (outdated), INFO (style).
+
+  (g) Origin Field Validation (optional fields — backward compatible):
+      The origin and origin_ref fields are OPTIONAL — stories without these fields
+      are valid (backward compatibility). Missing origin/origin_ref fields do NOT
+      cause errors and are accepted without warnings.
+      If the origin field IS present, validate:
+        - origin must be one of: "manual", "problem-solving", "triage", "add-feature",
+          "sprint-planning", or null. An invalid origin enum value is a CRITICAL finding.
+        - If origin is non-null, origin_ref must be non-empty (not null, not empty string).
+          A non-null origin with empty or null origin_ref is a WARNING finding.
+      If origin is null or absent, origin_ref is not validated (orphaned refs are acceptable).
   </action>
 </step>
 <step n="3" title="Validation Fix Loop">

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

@@ -124,23 +124,26 @@
   **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):
+  Deep analysis scan outputs (7 files — Step 2.5):
   - {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-hardcoded.md
+  - {planning_artifacts}/brownfield-scan-security.md
   - {planning_artifacts}/brownfield-scan-runtime-behavior.md
-  - {planning_artifacts}/brownfield-scan-doc-code-drift.md
+  - {planning_artifacts}/brownfield-scan-doc-code.md
   - {planning_artifacts}/brownfield-scan-integration-seam.md
 
-  Step 2 documentation subagent outputs:
+  Test execution scan output (1 file — Step 2.75):
+  - {planning_artifacts}/brownfield-scan-test-execution.md (failing tests as gap entries)
+
+  Step 2 documentation subagent outputs (4 files):
   - {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 3 NFR assessment:
+  - {test_artifacts}/nfr-assessment.md (NFR 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.
@@ -197,6 +200,7 @@
   — 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>— project-documentation.md → project context: tech stack, architecture patterns, conventions, detected capability flags, CI/CD summary. Use for PRD Overview section (existing project summary) and to ground gap requirements in the actual project structure.</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>

package/_gaia/testing/workflows/test-gap-analysis/checklist.md

@@ -0,0 +1,8 @@
+# Test Gap Analysis Checklist
+- [ ] Execution mode determined (coverage or verification)
+- [ ] Test plan scanned for test case IDs and story links
+- [ ] Story files scanned for acceptance criteria
+- [ ] Cross-reference completed — gaps identified
+- [ ] Output follows FR-223 schema (summary count, per-story table, coverage %)
+- [ ] Zero-gap case handled with "No coverage gaps detected" message
+- [ ] Workflow completed within NFR-040 performance constraint (< 60 seconds)

package/_gaia/testing/workflows/test-gap-analysis/instructions.xml

@@ -0,0 +1,53 @@
+<workflow name="test-gap-analysis">
+<critical>
+  <mandate>Scan test-plan.md and story files to identify acceptance criteria gaps — NFR-040 requires completion in under 60 seconds</mandate>
+  <mandate>Output must follow the FR-223 schema: summary count, per-story gap table, coverage percentage</mandate>
+  <mandate>When no gaps are detected, output must state "No coverage gaps detected" with a summary count of zero</mandate>
+</critical>
+
+<step n="1" title="Determine Mode">
+  <action>Check the --mode argument: coverage or verification</action>
+  <action>If no mode specified, default to coverage mode</action>
+  <action>If mode is 'verification', skip to verification-mode steps (E19-S2 scope — not implemented yet)</action>
+</step>
+
+<step n="2" title="Scan Test Plan">
+  <action>Read {test_artifacts}/test-plan.md</action>
+  <action>Extract all test case IDs and their linked story keys from the test plan</action>
+  <action>Build a map of test_case_id -> [story_keys] for cross-referencing</action>
+  <action>If test-plan.md is missing, log warning: "test-plan.md not found — partial coverage analysis only" and continue with empty test case map</action>
+</step>
+
+<step n="3" title="Scan Story Files">
+  <action>Scan all story files in docs/implementation-artifacts/ matching pattern {story_key}-*.md</action>
+  <action>For each story file, extract all acceptance criteria (AC items) from the "Acceptance Criteria" section</action>
+  <action>Build a map of story_key -> [AC items] with their identifiers (AC1, AC2, etc.)</action>
+  <action>Track untested acceptance criteria — ACs that have no matching test case in the test plan map</action>
+</step>
+
+<step n="4" title="Cross-Reference and Identify Gaps">
+  <action>For each story's acceptance criteria, check if a corresponding test case exists in the test plan</action>
+  <action>Flag each AC as covered (has test case) or uncovered-ac (no test case found)</action>
+  <action>Calculate coverage rate per story: covered_ACs / total_ACs</action>
+  <action>Calculate overall coverage percentage across all stories</action>
+</step>
+
+<step n="5" title="Generate Output (FR-223 Schema)">
+  <action>Generate the output artifact at {test_artifacts}/test-gap-analysis-{date}.md</action>
+  <action>Output must include the following FR-223 schema sections:
+    - Summary section with total count of stories analyzed, ACs scanned, gaps found, and overall coverage percentage
+    - Per-story gap table listing each story, its ACs, and their coverage status
+    - Coverage rate breakdown showing covered vs uncovered acceptance criteria
+  </action>
+  <action>If zero gaps are detected (all ACs have corresponding test cases):
+    Output "No coverage gaps detected" in the summary section with a gap count of 0 and coverage rate of 100%</action>
+  <template-output file="{test_artifacts}/test-gap-analysis-{date}.md">
+    Gap analysis report following FR-223 schema with summary count, per-story gap table, and coverage percentage.
+  </template-output>
+</step>
+
+<step n="6" title="Performance Validation">
+  <action>Verify workflow completed within the NFR-040 constraint of under 60 seconds</action>
+  <action>Log total execution time in the output footer</action>
+</step>
+</workflow>

package/_gaia/testing/workflows/test-gap-analysis/workflow.yaml

@@ -0,0 +1,38 @@
+name: test-gap-analysis
+description: 'Scan test suite against requirements to identify untested or under-tested areas'
+module: testing
+agent: test-architect
+execution_mode: planning
+modes:
+  - coverage
+  - verification
+default_mode: coverage
+config_resolved: "{installed_path}/.resolved/test-gap-analysis.yaml"
+config_source: "{project-root}/_gaia/testing/config.yaml"
+installed_path: "{project-root}/_gaia/testing/workflows/test-gap-analysis"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+traces_to:
+  - FR-221
+  - FR-223
+  - NFR-040
+performance_constraints:
+  max_duration_seconds: 60  # NFR-040 — workflow must complete in under 60 seconds
+input_file_patterns:
+  test_plan:
+    whole: "{test_artifacts}/test-plan.md"
+    load_strategy: "FULL_LOAD"
+  story_files:
+    whole: "{implementation_artifacts}/*.md"
+    load_strategy: "INDEX_GUIDED"
+  architecture:
+    whole: "{planning_artifacts}/architecture.md"
+    load_strategy: "INDEX_GUIDED"
+  sprint_status:
+    whole: "{implementation_artifacts}/sprint-status.yaml"
+    load_strategy: "FULL_LOAD"
+output:
+  primary: "{test_artifacts}/test-gap-analysis-{date}.md"
+on_error:
+  missing_file: "warn_and_continue"
+  unresolved_variable: "halt"

package/bin/gaia-framework.js

@@ -158,6 +158,8 @@ Commands:
   status     Show installation info
 
 Options:
+  --branch <name>   Clone from a specific branch
+  --staging         Shorthand for --branch staging
   --yes             Skip confirmation prompts
   --dry-run         Show what would be done without making changes
   --verbose         Show detailed progress
@@ -207,6 +209,32 @@ function main(deps) {
     fail(`Unknown command: ${command}\n   Run 'npx gaia-framework --help' for usage.`);
   }
 
+  // ─── Branch flag parsing (E14-S1) ─────────────────────────────────────────
+  // Extract --branch / --staging before building the passthrough array.
+  // These flags control which git branch is cloned — they are consumed by the
+  // JS CLI and forwarded as --branch <name> to gaia-install.sh.
+  let branchValue = null;
+  const remaining = args.slice(0);
+
+  const branchIdx = remaining.indexOf("--branch");
+  const hasStaging = remaining.includes("--staging");
+
+  if (branchIdx >= 0 && hasStaging) {
+    fail("Cannot use --branch and --staging together. Use --branch staging instead.");
+  }
+
+  if (branchIdx >= 0) {
+    const valueIdx = branchIdx + 1;
+    if (valueIdx >= remaining.length || remaining[valueIdx].startsWith("--")) {
+      fail("Missing value for --branch flag. Usage: --branch <name>");
+    }
+    branchValue = remaining[valueIdx];
+    remaining.splice(branchIdx, 2);
+  } else if (hasStaging) {
+    branchValue = "staging";
+    remaining.splice(remaining.indexOf("--staging"), 1);
+  }
+
   // Ensure git is available
   ensureGit();
 
@@ -237,8 +265,9 @@ function main(deps) {
 
   info("Cloning GAIA framework from GitHub...");
 
+  const branchCloneFlag = branchValue ? ` --branch ${branchValue}` : "";
   try {
-    _exec(`git clone --depth 1 ${REPO_URL} "${tempDir}"`, {
+    _exec(`git clone --depth 1${branchCloneFlag} ${REPO_URL} "${tempDir}"`, {
       stdio: ["ignore", "ignore", "pipe"],
     });
   } catch (err) {
@@ -256,10 +285,15 @@ function main(deps) {
 
   // Build the shell command: inject --source pointing to the temp clone
   // so the shell script doesn't need to clone again
-  const passthrough = args.slice(0);
+  const passthrough = remaining.slice(0);
   // Insert --source right after the command (convert to POSIX for bash on Windows)
   passthrough.splice(1, 0, "--source", toPosixPath(tempDir));
 
+  // Inject --branch flag for installer passthrough (E14-S1)
+  if (branchValue) {
+    passthrough.push("--branch", branchValue);
+  }
+
   // Locate bash (critical for Windows support)
   const bashPath = _findBash();
   if (!bashPath) {

package/bin/helpers/derive-bump-label.js

@@ -0,0 +1,41 @@
+/**
+ * Derive bump label from PR title conventional commit prefix.
+ * Used by .github/workflows/pr-title-label.yml (E14-S11, ADR-025).
+ *
+ * @param {string} title - PR title
+ * @param {string} body - PR body
+ * @returns {{ label: string, type: string, breaking: boolean } | null}
+ *   Returns the derived bump label info, or null if title doesn't match.
+ */
+
+const TITLE_REGEX = /^(feat|fix|refactor|perf|test|docs|chore|ci|style)(\(.+\))?(!)?: .+$/;
+
+const TYPE_TO_LABEL = Object.freeze({
+  feat: "bump:minor",
+  fix: "bump:patch",
+  perf: "bump:patch",
+  refactor: "bump:none",
+  test: "bump:none",
+  docs: "bump:none",
+  chore: "bump:none",
+  ci: "bump:none",
+  style: "bump:none",
+});
+
+function deriveBumpLabel(title, body) {
+  const match = title.match(TITLE_REGEX);
+  if (!match) return null;
+
+  const type = match[1];
+  const bang = match[3] === "!";
+  const bodyBreaking = typeof body === "string" && body.includes("BREAKING CHANGE");
+  const breaking = bang || bodyBreaking;
+
+  const label = breaking ? "bump:major" : TYPE_TO_LABEL[type];
+
+  return { label, type, breaking };
+}
+
+module.exports = deriveBumpLabel;
+module.exports.TITLE_REGEX = TITLE_REGEX;
+module.exports.TYPE_TO_LABEL = TYPE_TO_LABEL;

package/bin/helpers/validate-bump-labels.js

@@ -0,0 +1,38 @@
+/**
+ * PR bump label validation for staging merge enforcement.
+ * Used by .github/workflows/label-check.yml (E14-S6, ADR-025).
+ */
+
+const VALID_BUMP_LABELS = Object.freeze(["bump:major", "bump:minor", "bump:patch", "bump:none"]);
+
+/**
+ * Validate that exactly one bump:* label is present on a PR.
+ *
+ * @param {string[]} labels - Array of label names from the PR
+ * @returns {{ pass: boolean, message: string }} Validation result
+ */
+function validateBumpLabels(labels) {
+  const bumpLabels = labels.filter((label) => VALID_BUMP_LABELS.includes(label));
+
+  if (bumpLabels.length === 0) {
+    return {
+      pass: false,
+      message: `No bump label found. Add one of: ${VALID_BUMP_LABELS.join(", ")}`,
+    };
+  }
+
+  if (bumpLabels.length > 1) {
+    return {
+      pass: false,
+      message: `Multiple bump labels found: ${bumpLabels.join(", ")}. Exactly one required.`,
+    };
+  }
+
+  return {
+    pass: true,
+    message: `Valid bump label: ${bumpLabels[0]}`,
+  };
+}
+
+module.exports = validateBumpLabels;
+module.exports.VALID_BUMP_LABELS = VALID_BUMP_LABELS;

package/gaia-install.sh

@@ -76,6 +76,7 @@ TARGET=""
 OPT_YES=false
 OPT_DRY_RUN=false
 OPT_VERBOSE=false
+OPT_BRANCH=""
 
 # ─── Utility Functions ──────────────────────────────────────────────────────
 
@@ -95,7 +96,11 @@ clone_from_github() {
   fi
   TEMP_CLONE_DIR="$(mktemp -d "${TMPDIR:-/tmp}/gaia-framework-XXXXXX")"
   info "Cloning GAIA from GitHub..." >&2
-  if git clone --depth 1 "$GITHUB_REPO" "$TEMP_CLONE_DIR" 2>/dev/null; then
+  local branch_args=()
+  if [[ -n "$OPT_BRANCH" ]]; then
+    branch_args=(--branch "$OPT_BRANCH")
+  fi
+  if git clone --depth 1 "${branch_args[@]}" "$GITHUB_REPO" "$TEMP_CLONE_DIR" 2>/dev/null; then
     success "Cloned to temporary directory" >&2
   else
     error "Failed to clone from $GITHUB_REPO"
@@ -495,7 +500,7 @@ cmd_init() {
 
   # Step 8: Create custom directories (ADR-020: user-owned write targets)
   step "Creating custom directories..."
-  for cdir in skills templates; do
+  for cdir in skills templates stakeholders; do
     if [[ "$OPT_DRY_RUN" == true ]]; then
       detail "[dry-run] Would create: custom/$cdir/"
     else
@@ -628,6 +633,35 @@ cmd_update() {
     "_config/manifest.yaml"
   )
 
+  # ─── Migrate .customize.yaml files before _gaia/ overwrite (E10-S19, FR-153) ──
+  # Copy user customize.yaml files from _gaia/_config/agents/ to custom/skills/
+  # before the framework overwrite replaces _gaia/ contents with defaults.
+  # Copy-only semantics: originals are left in place as fallback (AC2).
+  step "Migrating customize.yaml files to custom/skills/..."
+  if [[ "$OPT_DRY_RUN" != true ]]; then
+    mkdir -p "$TARGET/custom/skills"
+  fi
+  local migrated=0
+  for cust_file in "$TARGET/_gaia/_config/agents/"*.customize.yaml; do
+    [[ -f "$cust_file" ]] || continue
+    local cust_basename
+    cust_basename="$(basename "$cust_file")"
+    if [[ -f "$TARGET/custom/skills/$cust_basename" ]]; then
+      [[ "$OPT_VERBOSE" == true ]] && detail "Skipped (already exists): custom/skills/$cust_basename"
+      continue
+    fi
+    if [[ "$OPT_DRY_RUN" == true ]]; then
+      detail "[dry-run] Would migrate: _gaia/_config/agents/$cust_basename → custom/skills/$cust_basename"
+    else
+      cp "$cust_file" "$TARGET/custom/skills/$cust_basename"
+      info "[migrate] _gaia/_config/agents/$cust_basename → custom/skills/$cust_basename"
+      migrated=$((migrated + 1))
+    fi
+  done
+  if [[ "$migrated" -gt 0 ]]; then
+    detail "Migrated $migrated customize.yaml file(s) to custom/skills/"
+  fi
+
   step "Updating framework files..."
   local updated=0 skipped=0 changed=0
 
@@ -690,7 +724,7 @@ cmd_update() {
   done
 
   # Ensure custom directories exist (user-owned, never overwritten — ADR-020)
-  for cdir in skills templates; do
+  for cdir in skills templates stakeholders; do
     if [[ "$OPT_DRY_RUN" == true ]]; then
       [[ ! -d "$TARGET/custom/$cdir" ]] && detail "[dry-run] Would create: custom/$cdir/"
     else
@@ -740,6 +774,29 @@ cmd_update() {
     fi
   fi
 
+  # ─── Post-install verification: check skill references in customize.yaml (E10-S19, AC4) ──
+  step "Verifying skill references in custom/skills/*.customize.yaml..."
+  for cust_file in "$TARGET/custom/skills/"*.customize.yaml; do
+    [[ -f "$cust_file" ]] || continue
+    local cust_name
+    cust_name="$(basename "$cust_file")"
+    # Extract source: values from customize.yaml (simple grep — no full YAML parser needed)
+    while IFS= read -r source_line; do
+      # Strip key prefix, leading whitespace, and surrounding quotes via parameter expansion
+      local ref_path="${source_line#*source:}"
+      ref_path="${ref_path#"${ref_path%%[![:space:]]*}"}"  # trim leading whitespace
+      ref_path="${ref_path#[\"\']}"                        # trim leading quote
+      ref_path="${ref_path%[\"\']}"                        # trim trailing quote
+      [[ -z "$ref_path" ]] && continue
+      # Resolve relative paths against TARGET
+      local full_path="$TARGET/$ref_path"
+      [[ "$ref_path" == /* ]] && full_path="$ref_path"
+      if [[ ! -f "$full_path" ]]; then
+        warn "[warn] Broken skill reference in $cust_name: $ref_path not found"
+      fi
+    done < <(grep 'source:' "$cust_file" || true)
+  done
+
   # Summary
   echo ""
   if [[ -d "$backup_dir" ]]; then
@@ -832,9 +889,10 @@ cmd_validate() {
     [[ -d "$TARGET/docs/$dir" ]]; check "Docs: $dir" $?
   done
 
-  # Custom directories (ADR-020: user-owned write targets)
+  # Custom directories (ADR-020: user-owned write targets, ADR-026: stakeholder agents)
   [[ -d "$TARGET/custom/skills" ]]; check "custom/skills/ exists" $?
   [[ -d "$TARGET/custom/templates" ]]; check "custom/templates/ exists" $?
+  [[ -d "$TARGET/custom/stakeholders" ]]; check "custom/stakeholders/ exists" $?
 
   # Version
   local version
@@ -938,6 +996,7 @@ ${BOLD}Commands:${RESET}
 
 ${BOLD}Options:${RESET}
   --source <path>   Local GAIA source (or clones from GitHub if omitted)
+  --branch <name>   Clone from a specific branch
   --yes             Skip confirmation prompts
   --dry-run         Show what would be done without making changes
   --verbose         Show detailed progress
@@ -1011,6 +1070,14 @@ parse_args() {
         OPT_VERBOSE=true
         shift
         ;;
+      --branch)
+        if [[ -z "${2:-}" ]]; then
+          error "--branch requires a branch name argument"
+          exit 1
+        fi
+        OPT_BRANCH="$2"
+        shift 2
+        ;;
       --help|-h)
         usage
         exit 0

package/package.json

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

package/_gaia/_memory/tier2-results/checkpoint-resume-2026-03-24.yaml

@@ -1,6 +0,0 @@
-test_name: "checkpoint-resume-reliability"
-date: "2026-03-24"
-result: "pass"
-observations: "All 10 test scenarios passed. Checkpoint validation (schema, checksums, legacy format), resume state reconstruction (happy path, error cases), and file modification detection (modified, deleted) all verified. 45 total tests: 31 unit + 14 Tier 2."
-runner: "Cleo (typescript-dev)"
-framework_version: "1.48.3"

package/_gaia/_memory/tier2-results/engine-scenarios-2026-03-22.yaml

@@ -1,14 +0,0 @@
-test_name: engine-scenarios
-date: "2026-03-22T00:00:00Z"
-result: pass
-observations: |
-  All 6 ACs validated via 18 structural tests:
-  - AC1: Step ordering verified in workflow.xml and dev-story instructions.xml (4 tests)
-  - AC2: Checkpoint YAML schema validated with all required fields (3 tests)
-  - AC3: Quality gate structure validated across all workflow configs (3 tests)
-  - AC4: Variable resolution verified — all vars in known set, engine requires global.yaml (3 tests)
-  - AC5: Execution mode switching definitions validated in workflow.xml (3 tests)
-  - AC6: tier2-results directory exists, result YAML schema validated (2 tests)
-  Zero regressions in existing Tier 1 tests (3486 passing).
-runner: vitest
-framework_version: "1.45.0"