@moretea-labs/forge 1.5.0-rc.1

package/scripts/export-requirement-portfolio.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+import { resolve } from 'path';
+import { exportRequirementPortfolio } from '../src/cli/controller/requirement-portfolio-export';
+import { resolveRepoPreferredControllerHome } from '../src/cli/repositories/controller-home';
+
+function valueAfter(args: string[], flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+try {
+  const args = process.argv.slice(2);
+  const repoRoot = resolve(valueAfter(args, '--repo') ?? process.cwd());
+  const repoId = valueAfter(args, '--repo-id')?.trim();
+  const outputDir = valueAfter(args, '--output');
+  if (!repoId) throw new Error('--repo-id is required');
+  if (!outputDir) throw new Error('--output is required');
+  const manifest = exportRequirementPortfolio({
+    controllerHome: resolveRepoPreferredControllerHome(repoRoot, valueAfter(args, '--controller-home')),
+    repoId,
+    repoRoot,
+    outputDir: resolve(outputDir),
+  });
+  console.log(JSON.stringify(manifest, null, 2));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/scripts/factor-lab-check.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Inspect factor registry health and candidate completeness.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+REGISTRY="$REPO_ROOT/tasks/factors/registry.json"
+
+if [[ ! -f "$REGISTRY" ]]; then
+  echo "Missing factor registry: $REGISTRY" >&2
+  exit 1
+fi
+
+JS_RUNTIME=""
+if command -v node >/dev/null 2>&1; then JS_RUNTIME=node
+elif command -v bun >/dev/null 2>&1; then JS_RUNTIME=bun
+else echo "No JavaScript runtime (node or bun) found" >&2; exit 1; fi
+
+$JS_RUNTIME - "$REGISTRY" "$REPO_ROOT" <<'NODE_EOF'
+const fs = require("fs");
+const path = require("path");
+
+const [,, registryPath, repoRoot] = process.argv;
+const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+const candidates = registry.candidates ?? [];
+const promoted = registry.promoted ?? [];
+const rejected = registry.rejected ?? [];
+
+console.log(`[FactorFactory] Candidates: ${candidates.length}`);
+console.log(`[FactorFactory] Promoted: ${promoted.length}`);
+console.log(`[FactorFactory] Rejected: ${rejected.length}`);
+
+let failures = 0;
+
+for (const candidate of candidates) {
+  const baseDir = path.join(repoRoot, ".claude", ".factor-cache", "candidates", candidate.slug);
+  const hypothesisPath = path.join(baseDir, "hypothesis.md");
+  const backtestSummaryPath = path.join(baseDir, "backtest-summary.md");
+
+  if (!fs.existsSync(hypothesisPath)) {
+    console.log(`[FactorFactory] ERROR ${candidate.slug}: missing hypothesis.md`);
+    failures += 1;
+    continue;
+  }
+
+  const hypothesis = fs.readFileSync(hypothesisPath, "utf8");
+  if (!hypothesis.includes("data_deps:")) {
+    console.log(`[FactorFactory] WARN ${candidate.slug}: hypothesis is missing data_deps`);
+  }
+
+  if (fs.existsSync(backtestSummaryPath)) {
+    const report = fs.readFileSync(backtestSummaryPath, "utf8");
+    if (!/Transaction Cost/i.test(report)) {
+      console.log(`[FactorFactory] WARN ${candidate.slug}: backtest-summary.md is missing transaction cost review`);
+    }
+  } else {
+    console.log(`[FactorFactory] WARN ${candidate.slug}: backtest-summary.md not generated yet`);
+  }
+}
+
+for (const entry of promoted) {
+  const promotedDir = path.join(repoRoot, "tasks", "factors", "promoted", entry.slug);
+  if (!fs.existsSync(promotedDir)) {
+    console.log(`[FactorFactory] ERROR ${entry.slug}: registry promoted entry missing filesystem directory`);
+    failures += 1;
+  }
+}
+
+if (failures > 0) {
+  process.exit(1);
+}
+NODE_EOF

package/scripts/factor-lab-new.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# Create a new factor candidate workspace and register it.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+NAME=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name) NAME="${2:-}"; shift 2 ;;
+    --help)
+      echo "Usage: bash scripts/factor-lab-new.sh --name <slug>"
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$NAME" ]]; then
+  echo "--name is required" >&2
+  exit 1
+fi
+
+SLUG="$(printf '%s' "$NAME" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
+if [[ -z "$SLUG" ]]; then
+  echo "Unable to derive a valid slug from name: $NAME" >&2
+  exit 1
+fi
+
+REGISTRY="$REPO_ROOT/tasks/factors/registry.json"
+CANDIDATE_DIR="$REPO_ROOT/.claude/.factor-cache/candidates/$SLUG"
+HYPOTHESIS_TEMPLATE="$REPO_ROOT/.claude/factor-factory/hypothesis.template.md"
+
+mkdir -p "$CANDIDATE_DIR/raw-backtest"
+
+if [[ ! -f "$REGISTRY" ]]; then
+  echo "Missing factor registry: $REGISTRY" >&2
+  exit 1
+fi
+
+JS_RUNTIME=""
+if command -v node >/dev/null 2>&1; then JS_RUNTIME=node
+elif command -v bun >/dev/null 2>&1; then JS_RUNTIME=bun
+else echo "No JavaScript runtime (node or bun) found" >&2; exit 1; fi
+
+$JS_RUNTIME - "$REGISTRY" "$SLUG" <<'NODE_EOF'
+const fs = require("fs");
+const [,, registryPath, slug] = process.argv;
+const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+
+registry.candidates ??= [];
+registry.promoted ??= [];
+registry.rejected ??= [];
+
+if (registry.candidates.some((entry) => entry.slug === slug) ||
+    registry.promoted.some((entry) => entry.slug === slug) ||
+    registry.rejected.some((entry) => entry.slug === slug)) {
+  console.error(`Factor already exists in registry: ${slug}`);
+  process.exit(1);
+}
+
+registry.candidates.push({
+  slug,
+  status: "candidate",
+  created_at: new Date().toISOString()
+});
+
+fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2) + "\n");
+NODE_EOF
+
+if [[ -f "$HYPOTHESIS_TEMPLATE" ]]; then
+  sed \
+    -e "s/{{FACTOR_ID}}/$SLUG/g" \
+    -e "s/{{FACTOR_NAME}}/$NAME/g" \
+    "$HYPOTHESIS_TEMPLATE" > "$CANDIDATE_DIR/hypothesis.md"
+else
+  cat > "$CANDIDATE_DIR/hypothesis.md" <<EOF_HYPOTHESIS
+---
+factor_id: "$SLUG"
+category: "momentum"
+confidence: "medium"
+data_deps:
+  - ohlcv
+---
+
+# $NAME Hypothesis
+EOF_HYPOTHESIS
+fi
+
+echo "[FactorFactory] Created candidate ${SLUG}"

package/scripts/factor-lab-promote.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# Promote a factor candidate into the committed registry.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+NAME=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name) NAME="${2:-}"; shift 2 ;;
+    --help)
+      echo "Usage: bash scripts/factor-lab-promote.sh --name <slug>"
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$NAME" ]]; then
+  echo "--name is required" >&2
+  exit 1
+fi
+
+SLUG="$(printf '%s' "$NAME" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
+REGISTRY="$REPO_ROOT/tasks/factors/registry.json"
+CANDIDATE_DIR="$REPO_ROOT/.claude/.factor-cache/candidates/$SLUG"
+PROMOTED_DIR="$REPO_ROOT/tasks/factors/promoted/$SLUG"
+
+if [[ ! -f "$CANDIDATE_DIR/hypothesis.md" ]]; then
+  echo "Missing candidate hypothesis: $CANDIDATE_DIR/hypothesis.md" >&2
+  exit 1
+fi
+
+if [[ ! -f "$CANDIDATE_DIR/backtest-summary.md" ]]; then
+  echo "Missing candidate backtest summary: $CANDIDATE_DIR/backtest-summary.md" >&2
+  exit 1
+fi
+
+mkdir -p "$PROMOTED_DIR/backtest-data"
+cp "$CANDIDATE_DIR/hypothesis.md" "$PROMOTED_DIR/hypothesis.md"
+cp "$CANDIDATE_DIR/backtest-summary.md" "$PROMOTED_DIR/backtest-summary.md"
+
+if [[ -d "$CANDIDATE_DIR/raw-backtest" ]]; then
+  cp -R "$CANDIDATE_DIR/raw-backtest"/. "$PROMOTED_DIR/backtest-data/"
+fi
+
+JS_RUNTIME=""
+if command -v node >/dev/null 2>&1; then JS_RUNTIME=node
+elif command -v bun >/dev/null 2>&1; then JS_RUNTIME=bun
+else echo "No JavaScript runtime (node or bun) found" >&2; exit 1; fi
+
+$JS_RUNTIME - "$REGISTRY" "$SLUG" <<'NODE_EOF'
+const fs = require("fs");
+const [,, registryPath, slug] = process.argv;
+const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+
+registry.candidates ??= [];
+registry.promoted ??= [];
+registry.rejected ??= [];
+
+const idx = registry.candidates.findIndex((entry) => entry.slug === slug);
+if (idx === -1) {
+  console.error(`Candidate not found in registry: ${slug}`);
+  process.exit(1);
+}
+
+const candidate = registry.candidates[idx];
+registry.candidates.splice(idx, 1);
+registry.promoted.push({
+  slug,
+  promoted_at: new Date().toISOString(),
+  source: candidate
+});
+
+fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2) + "\n");
+NODE_EOF
+
+rm -rf "$CANDIDATE_DIR"
+
+echo "[FactorFactory] Promoted factor ${SLUG}"

package/scripts/factor-lab-reject.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# Reject a factor candidate and record the reason.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+NAME=""
+REASON=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name) NAME="${2:-}"; shift 2 ;;
+    --reason) REASON="${2:-}"; shift 2 ;;
+    --help)
+      echo "Usage: bash scripts/factor-lab-reject.sh --name <slug> --reason <text>"
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$NAME" || -z "$REASON" ]]; then
+  echo "--name and --reason are required" >&2
+  exit 1
+fi
+
+SLUG="$(printf '%s' "$NAME" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
+REGISTRY="$REPO_ROOT/tasks/factors/registry.json"
+CANDIDATE_DIR="$REPO_ROOT/.claude/.factor-cache/candidates/$SLUG"
+
+JS_RUNTIME=""
+if command -v node >/dev/null 2>&1; then JS_RUNTIME=node
+elif command -v bun >/dev/null 2>&1; then JS_RUNTIME=bun
+else echo "No JavaScript runtime (node or bun) found" >&2; exit 1; fi
+
+$JS_RUNTIME - "$REGISTRY" "$SLUG" "$REASON" <<'NODE_EOF'
+const fs = require("fs");
+const [,, registryPath, slug, reason] = process.argv;
+const registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+
+registry.candidates ??= [];
+registry.promoted ??= [];
+registry.rejected ??= [];
+
+const idx = registry.candidates.findIndex((entry) => entry.slug === slug);
+if (idx === -1) {
+  console.error(`Candidate not found in registry: ${slug}`);
+  process.exit(1);
+}
+
+registry.candidates.splice(idx, 1);
+registry.rejected.push({
+  slug,
+  reason,
+  rejected_at: new Date().toISOString()
+});
+
+fs.writeFileSync(registryPath, JSON.stringify(registry, null, 2) + "\n");
+NODE_EOF
+
+rm -rf "$CANDIDATE_DIR"
+
+echo "[FactorFactory] Rejected factor ${SLUG}"

package/scripts/harness-trace-grade.sh

@@ -0,0 +1,150 @@
+#!/bin/bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE_EOF'
+Usage: scripts/harness-trace-grade.sh --run <trace.json> [--repo <repo>] [--strict]
+USAGE_EOF
+}
+
+run_file=""
+repo="."
+strict=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --run)
+      run_file="${2:-}"
+      shift 2
+      ;;
+    --repo)
+      repo="${2:-.}"
+      shift 2
+      ;;
+    --strict)
+      strict=1
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+[[ -n "$run_file" ]] || { usage >&2; exit 1; }
+[[ -f "$run_file" ]] || { echo "Trace run file not found: $run_file" >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { echo "jq is required for harness trace grading" >&2; exit 1; }
+
+if REPO_ROOT="$(cd "$repo" && pwd -P 2>/dev/null)"; then
+  :
+else
+  echo "Repo path not found: $repo" >&2
+  exit 1
+fi
+
+results_file="$(mktemp)"
+trap 'rm -f "$results_file"' EXIT
+: > "$results_file"
+
+record() {
+  local id="$1"
+  local passed="$2"
+  local message="$3"
+  jq -n \
+    --arg id "$id" \
+    --argjson passed "$passed" \
+    --arg message "$message" \
+    '{id: $id, passed: $passed, message: $message}' >> "$results_file"
+}
+
+trace_get() {
+  local query="$1"
+  jq -r "$query // empty" "$run_file"
+}
+
+schema="$(trace_get '.schema')"
+active_plan="$(trace_get '.active_plan')"
+task_profile="$(trace_get '.task_profile')"
+review_card_verdict="$(trace_get '.review.card.verdict')"
+review_card_change_type="$(trace_get '.review.card.change_type')"
+review_card_rollback="$(trace_get '.review.card.rollback')"
+commands_count="$(jq '.commands | if type == "array" then length else 0 end' "$run_file")"
+outside_count="$(jq '.allowed_paths_check.outside | if type == "array" then length else 0 end' "$run_file")"
+allowed_status="$(trace_get '.allowed_paths_check.status')"
+
+if [[ "$schema" == "forge-run-trace.v1" ]]; then
+  record "schema.v1" true "trace schema is forge-run-trace.v1"
+else
+  record "schema.v1" false "trace schema is ${schema:-missing}"
+fi
+
+if [[ -n "$active_plan" && -f "$REPO_ROOT/$active_plan" ]]; then
+  record "active_plan.resolves" true "active plan resolves: $active_plan"
+else
+  record "active_plan.resolves" false "active plan does not resolve: ${active_plan:-missing}"
+fi
+
+case "$task_profile" in
+  code-change|docs-only|ledger-closeout|migration|eval-only|delegated-run)
+    record "contract_profile.valid" true "contract profile is valid: $task_profile"
+    ;;
+  *)
+    record "contract_profile.valid" false "contract profile is invalid: ${task_profile:-missing}"
+    ;;
+esac
+
+if [[ "$review_card_verdict" == "pass" ]]; then
+  record "review_card.pass" true "Human Review Card verdict is pass"
+else
+  record "review_card.pass" false "Human Review Card verdict is ${review_card_verdict:-missing}"
+fi
+
+if [[ -n "$review_card_change_type" && "$review_card_change_type" == "$task_profile" ]]; then
+  record "review_card.change_type" true "Human Review Card change type matches task profile"
+else
+  record "review_card.change_type" false "Human Review Card change type ${review_card_change_type:-missing} does not match task profile ${task_profile:-missing}"
+fi
+
+rollback_token="$(printf '%s' "$review_card_rollback" | sed -E 's/[;,].*$//; s/[[:space:]].*$//; s/^[[:space:]]+//; s/[[:space:]]+$//' | tr '[:upper:]' '[:lower:]')"
+case "$rollback_token" in
+  ""|tbd|todo|n/a|na|none|unknown|unavailable|pending|...)
+    record "review_card.rollback" false "Human Review Card rollback is missing or not concrete"
+    ;;
+  *)
+    record "review_card.rollback" true "Human Review Card rollback is concrete"
+    ;;
+esac
+
+if [[ "$commands_count" -gt 0 ]] && jq -e '.commands[]? | select((.command // "") | length > 0)' "$run_file" >/dev/null; then
+  record "commands.present" true "commands evidence is present"
+else
+  record "commands.present" false "commands evidence is missing"
+fi
+
+if [[ "$outside_count" -eq 0 && "$allowed_status" == "pass" ]]; then
+  record "allowed_paths.clean" true "no changed file is outside allowed paths"
+else
+  record "allowed_paths.clean" false "allowed_paths status is ${allowed_status:-missing}; changed files outside allowed paths: $outside_count"
+fi
+
+failed="$(jq -s '[.[] | select(.passed == false)] | length' "$results_file")"
+total="$(jq -s 'length' "$results_file")"
+status="pass"
+[[ "$failed" -eq 0 ]] || status="fail"
+
+jq -s \
+  --arg status "$status" \
+  --arg run "$run_file" \
+  --argjson total "$total" \
+  --argjson failed "$failed" \
+  '{status: $status, run: $run, total: $total, failed: $failed, graders: .}' "$results_file"
+
+if [[ "$strict" -eq 1 && "$failed" -ne 0 ]]; then
+  exit 1
+fi