gennady 0.7.0 → 0.8.0

package/dist/ai/skills/sdd-execute/scripts/check-blockers.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# @file: Scan ticket Execution Log for unresolved BLOCKER entries.
+# @consumers: orchestrator (preflight before phase dispatch); audit; CI hooks.
+# @contract: AX_BASH_NO_SILENT_EMPTY. Implements AX_BLOCKER_RESOLUTION_TRAIL —
+#            BLOCKER from earlier Round is ACTIVE unless a later Round explicitly
+#            marks it RESOLVED.
+#
+# Heuristic detection:
+#   - Lines containing both "🛑" AND "BLOCKED" → blocker entry (with line number, context).
+#   - Lines containing both "✅" AND "RESOLVED" → resolution marker.
+#   - If RESOLVED markers count >= BLOCKED markers count, AND the last 🛑/✅ marker
+#     in the log is ✅ → all blockers considered resolved.
+#   - Otherwise → list latest blocker entries as ACTIVE; orchestrator must decide.
+#
+# Usage:
+#   check-blockers.sh <ticket-file>
+#
+# Exit codes:
+#   0  — no unresolved blockers (clear to dispatch)
+#   2  — one or more unresolved blockers (orchestrator MUST resolve before dispatch)
+#   4  — bad invocation
+#   1  — file not found
+
+set -uo pipefail
+
+PROG="check-blockers"
+
+if [[ $# -ne 1 ]]; then
+    cat <<EOF
+[$PROG] BAD_INVOCATION
+  expected: $PROG <ticket-file>
+  got:      $PROG $*
+
+Required action (ORCHESTRATOR):
+  Pass exactly one ticket file path.
+EOF
+    exit 4
+fi
+
+ticket="$1"
+
+if [[ ! -f "$ticket" ]]; then
+    cat <<EOF
+[$PROG] FILE_NOT_FOUND
+  file: $ticket
+
+Required action:
+  Verify ticket path; task may need re-resolution.
+EOF
+    exit 1
+fi
+
+# Locate Execution Log section start. Convention: "## 7. Execution Log".
+log_start=$(grep -n "^## 7\. Execution Log" "$ticket" | head -1 | cut -d: -f1)
+if [[ -z "$log_start" ]]; then
+    cat <<EOF
+[$PROG] NO_EXECUTION_LOG
+  file: $ticket
+
+The ticket lacks a "## 7. Execution Log" section. Either the ticket is malformed
+or uses a different section number/title.
+
+Required action (ORCHESTRATOR):
+  Verify ticket structure follows scaffold.directive convention. If structure is
+  correct but section title differs, update this script's heuristic accordingly.
+
+Treating as clear (no blockers detectable).
+EOF
+    exit 0
+fi
+
+# Extract Execution Log content
+log_content=$(tail -n +"$log_start" "$ticket")
+
+# Find blocker and resolution lines (with line numbers).
+# Use awk with proper line numbering, output to temp files for portability with macOS bash 3.2 (no mapfile).
+blocker_lines=()
+resolved_lines=()
+blocker_count=0
+resolved_count=0
+
+while IFS= read -r line; do
+    [[ -n "$line" ]] && blocker_lines+=("$line") && blocker_count=$((blocker_count + 1))
+done < <(grep -n "🛑.*BLOCKED\|BLOCKED.*🛑" "$ticket" 2>/dev/null | awk -F: -v start="$log_start" '$1 >= start { print $0 }')
+
+while IFS= read -r line; do
+    [[ -n "$line" ]] && resolved_lines+=("$line") && resolved_count=$((resolved_count + 1))
+done < <(grep -n "✅.*RESOLVED\|RESOLVED.*✅" "$ticket" 2>/dev/null | awk -F: -v start="$log_start" '$1 >= start { print $0 }')
+
+# Determine last marker (BLOCKER or RESOLUTION) by line number
+last_blocker_line=0
+last_resolved_line=0
+if [[ $blocker_count -gt 0 ]]; then
+    last_blocker_line=$(echo "${blocker_lines[$((blocker_count - 1))]}" | cut -d: -f1)
+fi
+if [[ $resolved_count -gt 0 ]]; then
+    last_resolved_line=$(echo "${resolved_lines[$((resolved_count - 1))]}" | cut -d: -f1)
+fi
+
+# ---------------------------------------------------------------------------
+# Verdict
+# ---------------------------------------------------------------------------
+
+if [[ $blocker_count -eq 0 ]]; then
+    cat <<EOF
+[$PROG] CLEAR
+  ticket: $ticket
+  blockers found: 0
+  status: no BLOCKER entries in Execution Log; clear to dispatch phase.
+EOF
+    exit 0
+fi
+
+if [[ $resolved_count -ge $blocker_count ]] && [[ $last_resolved_line -gt $last_blocker_line ]]; then
+    cat <<EOF
+[$PROG] CLEAR
+  ticket: $ticket
+  blockers found:   $blocker_count
+  resolutions:      $resolved_count
+  last marker:      ✅ RESOLVED on line $last_resolved_line
+  status: AX_BLOCKER_RESOLUTION_TRAIL satisfied — all blockers resolved.
+EOF
+    exit 0
+fi
+
+# Unresolved blockers — emit list
+cat <<EOF
+[$PROG] UNRESOLVED_BLOCKERS
+  ticket: $ticket
+  blockers found:   $blocker_count
+  resolutions:      $resolved_count
+  last 🛑 line:     $last_blocker_line
+  last ✅ line:     $last_resolved_line
+  status: AX_BLOCKER_RESOLUTION_TRAIL violated — latest marker is BLOCKER, not RESOLUTION.
+
+Active BLOCKER entries (last 5):
+EOF
+# Print last 5 elements portably (no slicing syntax that requires bash 4)
+start_idx=$((blocker_count - 5))
+[[ $start_idx -lt 0 ]] && start_idx=0
+i=$start_idx
+while [[ $i -lt $blocker_count ]]; do
+    echo "  ${blocker_lines[$i]}" | cut -c1-200
+    i=$((i + 1))
+done
+
+cat <<EOF
+
+Required action (ORCHESTRATOR):
+  1. Read the listed BLOCKER entries in the ticket.
+  2. Verify whether each blocker is still ACTIVE in current environment:
+     - If actually still blocking → escalate to operator with unblock options.
+     - If actually resolved (e.g. environment fixed, decision made) → append
+       Round N entry with "✅ RESOLVED <Round-M BLOCKER ref>: <reason>" line
+       to Execution Log; then re-run this script.
+  3. DO NOT dispatch phase agent while any blocker is unresolved.
+EOF
+exit 2

package/dist/ai/skills/sdd-execute/scripts/classify-scripts.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// @file: Heuristic npm script classifier — reads package.json, outputs discovered commands as JSON.
+// @consumers: verify.sh
+// @tasks: TSK-55, TSK-61
+//
+// Usage: node classify-scripts.js [project-root]
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function hasCategory(body, category) {
+  const patterns = {
+    tsc: /\b(tsc|tsgo)\b/,
+    lint: /\b(eslint|mail-core-lint\b|biome check\b|standard\b)\b/,
+    test: /\b(jest|vitest|playwright test|mocha\b|--test\b)\b/,
+    format: /\b(prettier|biome format)\b/,
+  };
+  return patterns[category] ? patterns[category].test(body) : false;
+}
+
+function classify(name, body) {
+  const isUmbrellaName = /^(check|ci-check|check:all|verify)$/.test(name);
+  if (isUmbrellaName && body.length > 0) return ['umbrella'];
+
+  const tc = hasCategory(body, 'tsc') ? 1 : 0;
+  const lc = hasCategory(body, 'lint') ? 1 : 0;
+  const sc = hasCategory(body, 'test') ? 1 : 0;
+  const hasGennady = /\bgennady\b/.test(body) || /lint:contracts/.test(body);
+  const hasChain = body.includes('&&');
+  const hasParallel = /[&]/.test(body) && /;\s*wait/.test(body);
+
+  if (tc + lc + sc >= 2 && (hasChain || hasParallel)) return ['umbrella'];
+  if (hasGennady && hasChain) return ['umbrella'];
+
+  const classes = [];
+  if (hasGennady) classes.push('gennady');
+
+  const typecheckName = /^(type-?check|typecheck|typecheck:|tsc)$/.test(name);
+  const typecheckBody = /\b(tsc|tsgo)\b/.test(body) && /--noEmit/.test(body);
+  if (
+    (typecheckName || typecheckBody || name === 'lint:ts') &&
+    !name.startsWith('build:') &&
+    !name.startsWith('prepublish')
+  )
+    classes.push('typecheck');
+
+  const lintName = /^(lint|lint:all|lint-check|eslint|mc:eslint|stylist:lint|stylelint)$/.test(
+    name
+  );
+  const lintBody = hasCategory(body, 'lint');
+  if (
+    (lintName || lintBody) &&
+    !name.startsWith('lint:fix') &&
+    !name.startsWith('lint:contracts') &&
+    !name.startsWith('lint:ts') &&
+    !hasGennady
+  )
+    classes.push('lint');
+
+  const testName = /^(test|test:|mc:test|mc:jest|jest)$/.test(name);
+  const testBody = hasCategory(body, 'test') || /\bnode\b.*--test\b/.test(body);
+  if (testName || (testBody && !name.startsWith('build:') && !name.startsWith('prepublish')))
+    classes.push('test');
+
+  const formatName = /^format(:?check)?$/.test(name);
+  const formatBody = hasCategory(body, 'format');
+  if (formatName || formatBody) classes.push('format');
+
+  return classes.length > 0 ? classes : ['unknown'];
+}
+
+function selectBest(entries, cls) {
+  const priority = {
+    typecheck: { 'type-check': 10, typecheck: 10, tsc: 5 },
+    gennady: { 'lint:contracts': 10 },
+    lint: { lint: 10, eslint: 7, 'lint:all': 5, 'lint-check': 5, 'mc:eslint': 3 },
+    test: { test: 10, 'test:unit': 7, 'mc:test': 5, 'mc:jest': 3, jest: 3 },
+    format: { 'format:check': 10, format: 5 },
+  };
+  const candidates = entries.filter((e) => e.classes.includes(cls));
+  if (candidates.length === 0) return undefined;
+  const rank = (name) => (priority[cls] && priority[cls][name]) || 1;
+  candidates.sort((a, b) => rank(b.name) - rank(a.name));
+  return candidates[0] ? candidates[0].name : undefined;
+}
+
+// --- Main ---
+const rootArg = process.argv.slice(2).find((a) => !a.startsWith('-'));
+const root = rootArg ? resolve(rootArg) : process.cwd();
+
+let pkg;
+try {
+  pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf-8'));
+} catch {
+  console.error(`[classify-scripts] package.json not found at ${root}`);
+  process.exit(1);
+}
+
+const entries = Object.entries(pkg.scripts || {}).map(([name, body]) => ({
+  name,
+  body,
+  classes: classify(name, body),
+}));
+
+const selected = {};
+for (const cls of ['typecheck', 'gennady', 'lint', 'test', 'format']) {
+  const best = selectBest(entries, cls);
+  if (best) selected[cls] = best;
+}
+
+process.stdout.write(JSON.stringify({ scripts: entries, selected }));

package/dist/ai/skills/sdd-execute/scripts/classify-scripts.ts

@@ -0,0 +1,133 @@
+#!/usr/bin/env -S node --import tsx
+// @file: Heuristic npm script classifier — reads package.json, outputs discovered commands as JSON.
+// @consumers: verify.sh
+// @tasks: TSK-55
+//
+// Usage:
+//   classify-scripts.ts [--json] [project-root]
+//
+// Output:
+//   --json (default):  JSON array [{name, body, classes}]
+//   no flag:           human-readable summary
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+type ScriptClass = 'typecheck' | 'gennady' | 'lint' | 'test' | 'format' | 'umbrella' | 'unknown';
+
+interface ScriptEntry {
+  name: string;
+  body: string;
+  classes: ScriptClass[];
+}
+
+interface ClassifiedProject {
+  scripts: ScriptEntry[];
+  selected: Partial<Record<ScriptClass, string>>;
+}
+
+function hasCategory(body: string, category: string): boolean {
+  const patterns: Record<string, RegExp> = {
+    tsc: /\b(tsc|tsgo)\b/,
+    lint: /\b(eslint|mail-core-lint\b|biome check\b|standard\b)\b/,
+    test: /\b(jest|vitest|playwright test|mocha\b|--test\b)\b/,
+    format: /\b(prettier|biome format)\b/,
+  };
+  return patterns[category]?.test(body) ?? false;
+}
+
+function classify(name: string, body: string): ScriptClass[] {
+  const isUmbrellaName = /^(check|ci-check|check:all|verify)$/.test(name);
+  if (isUmbrellaName && body.length > 0) return ['umbrella'];
+
+  const tscCount = hasCategory(body, 'tsc') ? 1 : 0;
+  const lintCount = hasCategory(body, 'lint') ? 1 : 0;
+  const testCount = hasCategory(body, 'test') ? 1 : 0;
+  const hasGennady = /\bgennady\b/.test(body) || /lint:contracts/.test(body);
+  const hasChain = body.includes('&&');
+  const hasParallel = /[&]/.test(body) && /;\s*wait/.test(body);
+
+  if (tscCount + lintCount + testCount >= 2 && (hasChain || hasParallel)) return ['umbrella'];
+  if (hasGennady && hasChain) return ['umbrella'];
+
+  const classes: ScriptClass[] = [];
+  if (hasGennady) classes.push('gennady');
+
+  const typecheckName = /^(type-?check|typecheck|typecheck:|tsc)$/.test(name);
+  const typecheckBody = /\b(tsc|tsgo)\b/.test(body) && /--noEmit/.test(body);
+  if (
+    (typecheckName || typecheckBody || name === 'lint:ts') &&
+    !name.startsWith('build:') &&
+    !name.startsWith('prepublish')
+  )
+    classes.push('typecheck');
+
+  const lintName = /^(lint|lint:all|lint-check|eslint|mc:eslint|stylist:lint|stylelint)$/.test(
+    name
+  );
+  const lintBody = hasCategory(body, 'lint');
+  if (
+    (lintName || lintBody) &&
+    !name.startsWith('lint:fix') &&
+    !name.startsWith('lint:contracts') &&
+    !name.startsWith('lint:ts') &&
+    !hasGennady
+  )
+    classes.push('lint');
+
+  const testName = /^(test|test:|mc:test|mc:jest|jest)$/.test(name);
+  const testBody = hasCategory(body, 'test') || /\bnode\b.*--test\b/.test(body);
+  if (testName || (testBody && !name.startsWith('build:') && !name.startsWith('prepublish')))
+    classes.push('test');
+
+  const formatName = /^format(:?check)?$/.test(name);
+  const formatBody = hasCategory(body, 'format');
+  if (formatName || formatBody) classes.push('format');
+
+  return classes.length > 0 ? classes : ['unknown'];
+}
+
+function selectBest(entries: ScriptEntry[], cls: ScriptClass): string | undefined {
+  const candidates = entries.filter((e) => e.classes.includes(cls));
+  if (candidates.length === 0) return undefined;
+
+  // Prefer shorter, more specific names
+  const priority: Record<string, number> = {
+    typecheck: { 'type-check': 10, typecheck: 10, tsc: 5 },
+    gennady: { 'lint:contracts': 10 },
+    lint: { lint: 10, eslint: 7, 'lint:all': 5, 'lint-check': 5, 'mc:eslint': 3 },
+    test: { test: 10, 'test:unit': 7, 'mc:test': 5, 'mc:jest': 3, jest: 3 },
+    format: { 'format:check': 10, format: 5 },
+  };
+
+  const rank = (name: string) => priority[cls]?.[name] ?? 1;
+  candidates.sort((a, b) => rank(b.name) - rank(a.name));
+  return candidates[0]?.name;
+}
+
+// --- Main ---
+const root = process.argv.slice(2).find((a) => !a.startsWith('-')) || process.cwd();
+const pkgPath = resolve(root, 'package.json');
+
+let pkg: { scripts?: Record<string, string> };
+try {
+  pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+} catch {
+  console.error(`[classify-scripts] package.json not found at ${pkgPath}`);
+  process.exit(1);
+}
+
+const entries: ScriptEntry[] = Object.entries(pkg.scripts ?? {}).map(([name, body]) => ({
+  name,
+  body,
+  classes: classify(name, body),
+}));
+
+const selected: Partial<Record<ScriptClass, string>> = {};
+for (const cls of ['typecheck', 'gennady', 'lint', 'test', 'format'] as ScriptClass[]) {
+  const best = selectBest(entries, cls);
+  if (best) selected[cls] = best;
+}
+
+const result: ClassifiedProject = { scripts: entries, selected };
+console.log(JSON.stringify(result));

package/dist/ai/skills/sdd-execute/scripts/extract-section.sh

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# @file: Extract a named section between <!--SECTION:<NAME>--> / <!--/SECTION:<NAME>--> markers from a markdown file.
+# @consumers: sdd-execute, sdd-execute-batch (L2 orchestrator prompt-building); phase agents (rules extraction)
+# @contract: AX_BASH_NO_SILENT_EMPTY — never produces empty stdout. On miss → emits actionable instruction for the orchestrator + exit ≠ 0.
+#
+# Anchor grammar (canonical, AX_TICKET_ANCHOR_FORMAT):
+#   Open marker:   <!--SECTION:<NAME>-->
+#   Close marker:  <!--/SECTION:<NAME>-->
+#   <NAME>:        ^[A-Z][A-Z0-9_]*$  (uppercase, starts with letter, alnum + underscore only)
+#   No quotes, no spaces, no attributes — atomic identifiers only.
+#
+# Canonical names: META, PHASES_OVERVIEW, PHASE_P1, PHASE_P2, PHASE_P1_FIX, BDD, VERIFICATION, TEST_COVERAGE, EXECUTION_LOG.
+#
+# Usage:
+#   extract-section.sh <file> <NAME>
+#
+# Examples:
+#   extract-section.sh ticket.md META
+#   extract-section.sh ticket.md PHASE_P1
+#   extract-section.sh ticket.md EXECUTION_LOG
+#
+# Exit codes:
+#   0  — section found, content emitted to stdout
+#   1  — file not found / unreadable
+#   2  — anchor markers not present in file
+#   3  — START found but END missing, or vice versa (corrupted markers), or duplicate occurrences
+#   4  — bad invocation (missing args, invalid NAME)
+
+set -uo pipefail
+
+PROG="extract-section"
+NAME_REGEX='^[A-Z][A-Z0-9_]*$'
+
+if [[ $# -ne 2 ]]; then
+    cat <<EOF
+[$PROG] BAD_INVOCATION
+  expected: $PROG <file> <NAME>
+  got:      $PROG $*
+
+Required action (ORCHESTRATOR):
+  Pass exactly 2 arguments — file path and SECTION name.
+  NAME must match: $NAME_REGEX
+  Examples of valid names: META, PHASES_OVERVIEW, PHASE_P1, BDD, EXECUTION_LOG.
+EOF
+    exit 4
+fi
+
+file="$1"
+name="$2"
+
+# ---------------------------------------------------------------------------
+# NAME validation
+# ---------------------------------------------------------------------------
+
+if [[ ! "$name" =~ $NAME_REGEX ]]; then
+    cat <<EOF
+[$PROG] INVALID_NAME
+  name: $name
+  rule: $NAME_REGEX
+
+Diagnosis: section name does not match canonical anchor grammar.
+
+Required action (ORCHESTRATOR):
+  1. Use uppercase letters, digits, and underscores only.
+  2. Start with a letter (not a digit or underscore).
+  3. No spaces, no quotes, no attributes inside the name.
+
+Canonical names: META, PHASES_OVERVIEW, PHASE_P1, PHASE_P2, PHASE_P1_FIX,
+BDD, VERIFICATION, TEST_COVERAGE, EXECUTION_LOG.
+
+If you need attributes (kind, rules, etc.) — put them inside the section content,
+NOT inside the anchor name. The anchor is an identifier only.
+EOF
+    exit 4
+fi
+
+# ---------------------------------------------------------------------------
+# File existence + readability
+# ---------------------------------------------------------------------------
+
+if [[ ! -f "$file" ]]; then
+    cat <<EOF
+[$PROG] FILE_NOT_FOUND
+  file: $file
+
+Required action (ORCHESTRATOR):
+  1. Verify the file path argument (typos, wrong scope, wrong task-id).
+  2. Check whether the ticket/spec exists at the expected location.
+  3. If task ID resolves to a different path — fix the resolution layer, not this script.
+
+DO NOT proceed to dispatch phase agent until the file is located.
+EOF
+    exit 1
+fi
+
+if [[ ! -r "$file" ]]; then
+    cat <<EOF
+[$PROG] FILE_NOT_READABLE
+  file: $file
+  perms: $(stat -f '%Sp' "$file" 2>/dev/null || stat -c '%A' "$file" 2>/dev/null || echo 'unknown')
+
+Required action (ORCHESTRATOR):
+  Verify file permissions; chmod if needed.
+EOF
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Marker scan — pre-flight before extraction
+# ---------------------------------------------------------------------------
+
+start_marker="<!--SECTION:${name}-->"
+end_marker="<!--/SECTION:${name}-->"
+
+start_count=$(grep -cF "$start_marker" "$file" || true)
+end_count=$(grep -cF "$end_marker" "$file" || true)
+
+if [[ "$start_count" -eq 0 && "$end_count" -eq 0 ]]; then
+    cat <<EOF
+[$PROG] ANCHOR_NOT_FOUND
+  section: $name
+  file:    $file
+  searched markers:
+    $start_marker
+    $end_marker
+
+Diagnosis: file does not contain anchor markers for this section.
+
+Possible causes:
+  1. Ticket/spec scaffolded before anchor convention introduced (pre-2026-05-21).
+  2. Anchor was deleted or corrupted during manual edit.
+  3. Wrong section name — verify against canonical names
+     (META, PHASES_OVERVIEW, PHASE_P<N>, BDD, VERIFICATION, TEST_COVERAGE, EXECUTION_LOG).
+  4. Section uses non-canonical name — review file structure.
+
+Required action (ORCHESTRATOR, not phase agent):
+  1. Read the file directly via Read tool.
+  2. Verify the section exists by markdown header (e.g. ## 1. Meta, ### P1 — impl).
+  3. If section exists in header form but lacks anchors → retrofit anchors per
+      AX_TICKET_ANCHOR_FORMAT in ~/Developer/gennady/ai/directives/sdd/scaffold.directive.xml.
+  4. If section does not exist at all → escalate to operator: ticket needs
+     re-scaffolding or section content authoring.
+
+DO NOT proceed to dispatch a phase agent until anchors are in place.
+EOF
+    exit 2
+fi
+
+if [[ "$start_count" -ne "$end_count" ]]; then
+    cat <<EOF
+[$PROG] ANCHOR_UNBALANCED
+  section: $name
+  file:    $file
+  $start_marker count: $start_count
+  $end_marker   count: $end_count
+
+Diagnosis: markers are corrupted — counts of open and close markers do not match.
+
+Required action (ORCHESTRATOR):
+  1. Read the file.
+  2. Locate the imbalanced marker via:
+       grep -nF '$start_marker' "$file"
+       grep -nF '$end_marker'   "$file"
+  3. Restore the missing one OR remove the duplicate one.
+  4. Retry this script.
+
+DO NOT proceed to dispatch a phase agent until markers are balanced.
+EOF
+    exit 3
+fi
+
+if [[ "$start_count" -gt 1 ]]; then
+    cat <<EOF
+[$PROG] ANCHOR_DUPLICATED
+  section: $name
+  file:    $file
+  occurrences: $start_count
+
+Diagnosis: the same section appears more than once in this file — ambiguous extraction.
+
+Required action (ORCHESTRATOR):
+  1. Read the file and identify duplicate sections.
+  2. Either merge them or rename one to be unique (e.g. PHASE_P1 vs PHASE_P1_FIX).
+  3. Retry this script.
+EOF
+    exit 3
+fi
+
+# ---------------------------------------------------------------------------
+# Extraction — markers verified present and balanced; emit content between them.
+# Exclude the marker lines themselves from output.
+# ---------------------------------------------------------------------------
+
+content=$(awk -v start="$start_marker" -v end="$end_marker" '
+    $0 == start { in_block = 1; next }
+    $0 == end   { in_block = 0; next }
+    in_block    { print }
+' "$file")
+
+if [[ -z "$content" ]]; then
+    cat <<EOF
+[$PROG] ANCHOR_EMPTY
+  section: $name
+  file:    $file
+
+Diagnosis: markers are present and balanced, but the section between them is empty.
+
+Required action (ORCHESTRATOR):
+  1. Read the file.
+  2. Determine whether the section is intentionally empty (rare) or accidentally
+     stripped during refactor.
+  3. If accidental → re-author content.
+  4. If intentional → use a different section reference; this one carries no payload.
+EOF
+    exit 2
+fi
+
+printf '%s\n' "$content"
+exit 0