gennady 0.7.0 → 0.8.0

package/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/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

package/ai/skills/sdd-execute/scripts/lint-artifacts.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# @file: Run gennady lint on phase artifacts; parse output for success/failure (gennady exit-code unreliable).
+# @consumers: phase agents (STEP_5_VERIFY); audit subagents (STEP_1 pre-pass cross-check)
+# @contract: AX_BASH_NO_SILENT_EMPTY — never produces empty stdout. On miss → actionable instruction.
+#
+# Why this wrapper exists:
+#   - gennady CLI lives outside the project (canonical: ~/Developer/gennady/cli/gennady.ts).
+#   - gennady requires `node --experimental-strip-types` (Node 22+) — the bare `node` invocation is non-obvious.
+#   - gennady returns exit code 0 even when lint reports errors (the failure signal is the literal token
+#     "[linting → failed]" in stdout). We must parse output, not trust exit code.
+#   - Success signal is the literal token "[linting → clean] no errors".
+#
+# Usage:
+#   lint-artifacts.sh <file1> [<file2> ...]
+#
+# Exit codes:
+#   0 — all files clean (gennady output contains "[linting → clean]" and NOT "[linting → failed]")
+#   1 — gennady CLI not found / unable to invoke
+#   2 — lint reported errors (one or more violations); full output emitted
+#   3 — ambiguous output (neither "clean" nor "failed" token present); investigate gennady CLI changes
+#   4 — bad invocation (no args)
+
+set -uo pipefail
+
+PROG="lint-artifacts"
+GENNADY_CLI=~/Developer/gennady/cli/gennady.ts
+
+if [[ $# -lt 1 ]]; then
+    cat <<EOF
+[$PROG] BAD_INVOCATION
+  expected: $PROG <file1> [<file2> ...]
+  got:      $PROG (no args)
+
+Required action (ORCHESTRATOR / phase agent):
+  Pass at least one TypeScript file path to lint.
+  Typically: phase's Target Files list.
+EOF
+    exit 4
+fi
+
+if [[ ! -f "$GENNADY_CLI" ]]; then
+    cat <<EOF
+[$PROG] GENNADY_CLI_NOT_FOUND
+  expected at: $GENNADY_CLI
+
+Diagnosis: the gennady AST DbC linter is unreachable from this environment.
+
+Required action (ORCHESTRATOR):
+  1. Verify the gennady project is checked out at ~/Developer/gennady.
+  2. If gennady moved → update GENNADY_CLI variable in this script.
+  3. If on a CI/sandbox without gennady → this is a HARD blocker; phase cannot verify.
+     Report to operator: cannot complete phase without DBC contract verification.
+
+DO NOT proceed to EMIT_HANDOFF without gennady lint passing.
+EOF
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Run gennady lint and capture output
+# ---------------------------------------------------------------------------
+
+# Use a temp file to capture full output; we need both grep on it and to emit on failure.
+tmp_out=$(mktemp -t lint-artifacts.XXXXXX)
+trap 'rm -f "$tmp_out"' EXIT
+
+# Run gennady. We intentionally ignore its exit code (unreliable per contract above).
+npx tsx "$GENNADY_CLI" lint "$@" > "$tmp_out" 2>&1 || true
+
+has_clean=$(grep -c '\[linting → clean\]' "$tmp_out" 2>/dev/null || echo 0)
+has_failed=$(grep -c '\[linting → failed\]' "$tmp_out" 2>/dev/null || echo 0)
+
+# Convert to single-line numbers (grep -c with || echo 0 may produce odd output on some shells)
+has_clean=${has_clean//[^0-9]/}
+has_failed=${has_failed//[^0-9]/}
+has_clean=${has_clean:-0}
+has_failed=${has_failed:-0}
+
+# ---------------------------------------------------------------------------
+# Branch on tokens
+# ---------------------------------------------------------------------------
+
+if [[ "$has_failed" -gt 0 ]]; then
+    # Extract just the error lines (those with file:line: error: format) + final summary
+    cat <<EOF
+[$PROG] LINT_FAILED
+  files lint'd: $#
+  gennady output token: [linting → failed]
+
+Full lint output (gennady DBC AST findings):
+EOF
+    # Print error lines and the failure summary line
+    grep -E '\[linting → failed\]|: error: |^---|^References:|^  ' "$tmp_out" | head -200
+    echo
+    cat <<EOF
+---
+
+Required action (PHASE AGENT, before EMIT_HANDOFF):
+  1. Read each error: format is <file>:<line>:<col>: error: <ERR_CODE>: <message>
+  2. Common categories:
+     - ERR_DBC_LINT_PARAM_MISSING — add @param <name> <coherent-role-description>
+     - ERR_DBC_LINT_RETURNS_MISSING — add @returns <business-purpose-of-value>
+     - ERR_DBC_ORDER — reorder JSDoc tags per AX_BASE_CONTRACT_SHAPE:
+         @purpose → @consumers → @implements → @invariant → @pre →
+         @param → @throws → @returns → @post → @sideEffect
+  3. Fix all violations in the target files.
+  4. Re-run this script. Repeat until clean.
+  5. Do NOT EMIT_HANDOFF with lint failures present — that is fabricated DONE.
+
+References:
+  /Users/k.lebedev/Developer/vkt/ai/directives/coding/typescript-rules.xml
+  — AX_TAG_USAGE_MATRIX, AX_BASE_CONTRACT_SHAPE, AX_FLAT_JSDOC_FOR_PROPERTIES
+EOF
+    exit 2
+fi
+
+if [[ "$has_clean" -gt 0 ]]; then
+    # Clean. Emit concise PASS line to keep parent context light.
+    file_count=$#
+    echo "[$PROG] LINT_PASS"
+    echo "  files lint'd: $file_count"
+    echo "  gennady output token: [linting → clean]"
+    exit 0
+fi
+
+# Neither token found — gennady output format may have changed.
+cat <<EOF
+[$PROG] AMBIGUOUS_OUTPUT
+  files lint'd: $#
+  gennady output token: (neither "linting → clean" nor "linting → failed" found)
+
+Diagnosis: gennady CLI output format may have changed (or there is an unhandled edge case).
+
+Captured output:
+$(cat "$tmp_out" | head -50)
+
+Required action (ORCHESTRATOR):
+  1. Re-read gennady source: ~/Developer/gennady/cli/gennady.ts
+  2. Check command output tokens in the LintCommand implementation.
+  3. Update this script's parsing to match new tokens.
+  4. Until resolved → treat as a HARD blocker; DO NOT assume PASS.
+EOF
+exit 3