@moretea-labs/forge 1.5.1 → 1.7.0

package/src/testing/test-governance.ts

@@ -26,30 +26,24 @@ export type TestModule = (typeof TEST_MODULES)[number];
 export type TestResource = (typeof TEST_RESOURCES)[number];
 export type TestGate = 'affected' | 'core' | 'integration' | 'infrastructure' | 'fault' | 'full';
 
+/**
+ * Acceptance evidence is the default. Tests must protect externally observable
+ * contracts, migrations/rollback, failure injection, security boundaries, or
+ * a recorded production incident. Do not add tests for private helpers,
+ * implementation payloads, copy, enum order, or mock-only lifecycles.
+ */
+export const TEST_GOVERNANCE_POLICY = 'acceptance-first-no-internal-unit-tests' as const;
+
 export interface TestManifestEntry {
   module: TestModule;
   resource: TestResource;
   smoke?: boolean;
 }
 
-export interface TestBudgetPolicy {
-  maxTestFiles: number;
-  maxTestLines: number;
-  maxPureFiles: number;
-  maxTempIsolatedFiles: number;
-  maxProcessTreeFiles: number;
-  maxGitWorktreeFiles: number;
-  maxFixedPortFiles: number;
-  maxRuntimeSingletonFiles: number;
-  maxControllerHomeIsolatedFiles: number;
-  maxDestructiveFiles: number;
-}
-
 export interface TestManifest {
   version: 1;
   modules: TestModule[];
   resources: TestResource[];
-  policy: TestBudgetPolicy;
   pathModuleRules: Array<{ prefix: string; modules: TestModule[] }>;
   tests: Record<string, TestManifestEntry>;
 }
@@ -232,32 +226,6 @@ export function validateTestManifest(repoRoot: string, manifest = loadTestManife
     if (!TEST_RESOURCES.includes(entry.resource)) errors.push(`${file}: invalid resource ${String(entry.resource)}`);
   }
   if (!Object.values(manifest.tests).some((entry) => entry.smoke)) errors.push('manifest has no core smoke tests');
-  const resourceCounts = Object.values(manifest.tests).reduce<Record<string, number>>((counts, entry) => {
-    counts[entry.resource] = (counts[entry.resource] ?? 0) + 1;
-    return counts;
-  }, {});
-  const testLines = declaredFiles.reduce((total, file) => {
-    try {
-      return total + readFileSync(resolve(repoRoot, file), 'utf8').split('\n').length;
-    } catch (_error) {
-      return total;
-    }
-  }, 0);
-  const budgetChecks: Array<[string, number, number | undefined]> = [
-    ['maxTestFiles', declaredFiles.length, manifest.policy?.maxTestFiles],
-    ['maxTestLines', testLines, manifest.policy?.maxTestLines],
-    ['maxPureFiles', resourceCounts.pure ?? 0, manifest.policy?.maxPureFiles],
-    ['maxTempIsolatedFiles', resourceCounts['temp-isolated'] ?? 0, manifest.policy?.maxTempIsolatedFiles],
-    ['maxProcessTreeFiles', resourceCounts['process-tree'] ?? 0, manifest.policy?.maxProcessTreeFiles],
-    ['maxGitWorktreeFiles', resourceCounts['git-worktree'] ?? 0, manifest.policy?.maxGitWorktreeFiles],
-    ['maxFixedPortFiles', resourceCounts['fixed-port'] ?? 0, manifest.policy?.maxFixedPortFiles],
-    ['maxRuntimeSingletonFiles', resourceCounts['runtime-singleton'] ?? 0, manifest.policy?.maxRuntimeSingletonFiles],
-    ['maxControllerHomeIsolatedFiles', resourceCounts['controller-home-isolated'] ?? 0, manifest.policy?.maxControllerHomeIsolatedFiles],
-    ['maxDestructiveFiles', resourceCounts.destructive ?? 0, manifest.policy?.maxDestructiveFiles],
-  ];
-  for (const [name, actual, limit] of budgetChecks) {
-    if (typeof limit !== 'number' || actual > limit) errors.push(`test budget ${name} exceeded: ${actual} > ${String(limit)}`);
-  }
   return errors;
 }
 

package/assets/reference-configs/heartbeat-triage.md

@@ -1,57 +0,0 @@
-# Heartbeat Triage
-
-Heartbeat triage is the repo-local scheduled discovery loop. It records findings
-for a human to review; it does not approve plans, execute fixes, spawn agents,
-open PRs, or install a persistent scheduler.
-
-## Command
-
-Run from the repository root:
-
-```bash
-bash .ai/harness/scripts/heartbeat-triage.sh run --source scheduled
-```
-
-The command appends a run section to `.ai/harness/triage/inbox.md` and writes a
-JSON snapshot under `.ai/harness/runs/`. Each run records:
-
-- `workflow-check`: `bash .ai/harness/scripts/check-task-workflow.sh --strict`
-- `sprint-next`: `bash .ai/harness/scripts/sprint-backlog.sh next` when an active sprint
-  marker exists, with a read-only sprint-file fallback when it does not
-- `drift-requests`: pending files under `docs/architecture/requests/`
-
-## cron
-
-Example cron entry for a local checkout:
-
-```cron
-17 8 * * * cd /path/to/repo && bash .ai/harness/scripts/heartbeat-triage.sh run --source scheduled >/tmp/forge-heartbeat.log 2>&1
-```
-
-## loop
-
-Example long-running loop for a supervised terminal, launch wrapper, or local
-process manager:
-
-```bash
-while true; do
-  cd /path/to/repo && bash .ai/harness/scripts/heartbeat-triage.sh run --source scheduled
-  sleep 86400
-done
-```
-
-## Adoption Review
-
-Every run includes an "Adoption review due" date fourteen days out. The review
-question is narrow: did the inbox produce any human-accepted triage item? If no
-item is accepted during the review window, remove the scheduler and keep the
-runner as an on-demand diagnostic command.
-
-## Guardrails
-
-- Keep scheduler installation manual and host-local.
-- Treat workflow failures and drift requests as inbox entries, not process
-  crashes.
-- Keep `.ai/harness/triage/inbox.md` as runtime state, not a source-of-truth
-  plan or task ledger.
-- Keep execution authority in the normal plan -> contract -> verify flow.

package/assets/templates/helpers/harness-trace-grade.sh

@@ -1,150 +0,0 @@
-#!/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

package/assets/templates/helpers/heartbeat-triage.sh

@@ -1,361 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-usage() {
-  cat <<'USAGE_EOF'
-Usage: scripts/heartbeat-triage.sh [run] [--repo PATH] [--inbox PATH] [--run-id ID] [--source manual|scheduled] [--json]
-
-Writes a heartbeat triage run to .ai/harness/triage/inbox.md. The command is
-safe for cron/loop schedulers: findings are recorded as inbox entries and do
-not make the process fail unless the runner itself is misconfigured.
-USAGE_EOF
-}
-
-command="run"
-repo="."
-inbox_path=".ai/harness/triage/inbox.md"
-run_id=""
-run_source="manual"
-json_output=0
-
-if [[ "${1:-}" == "run" ]]; then
-  shift
-elif [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
-  usage
-  exit 0
-elif [[ "${1:-}" != "" && "${1:-}" != --* ]]; then
-  echo "heartbeat-triage: unknown command: $1" >&2
-  usage >&2
-  exit 2
-fi
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --repo)
-      [[ -n "${2:-}" ]] || { echo "heartbeat-triage: --repo requires a value" >&2; exit 2; }
-      repo="$2"
-      shift 2
-      ;;
-    --inbox)
-      [[ -n "${2:-}" ]] || { echo "heartbeat-triage: --inbox requires a value" >&2; exit 2; }
-      inbox_path="$2"
-      shift 2
-      ;;
-    --run-id)
-      [[ -n "${2:-}" ]] || { echo "heartbeat-triage: --run-id requires a value" >&2; exit 2; }
-      run_id="$2"
-      shift 2
-      ;;
-    --source)
-      [[ -n "${2:-}" ]] || { echo "heartbeat-triage: --source requires a value" >&2; exit 2; }
-      run_source="$2"
-      shift 2
-      ;;
-    --json)
-      json_output=1
-      shift
-      ;;
-    --help|-h)
-      usage
-      exit 0
-      ;;
-    *)
-      echo "heartbeat-triage: unknown argument: $1" >&2
-      usage >&2
-      exit 2
-      ;;
-  esac
-done
-
-[[ "$command" == "run" ]] || { echo "heartbeat-triage: unsupported command: $command" >&2; exit 2; }
-
-repo="$(cd "$repo" 2>/dev/null && pwd -P)" || { echo "heartbeat-triage: repo not found: $repo" >&2; exit 2; }
-cd "$repo"
-
-timestamp="$(date '+%Y-%m-%dT%H:%M:%S%z')"
-if [[ -z "$run_id" ]]; then
-  run_id="heartbeat-$(date '+%Y%m%dT%H%M%S')-$$"
-fi
-safe_run_id="$(printf '%s' "$run_id" | sed -E 's/[^A-Za-z0-9._-]+/-/g')"
-
-if [[ "$inbox_path" = /* ]]; then
-  inbox_file="$inbox_path"
-else
-  inbox_file="$repo/$inbox_path"
-fi
-
-runs_dir="$repo/.ai/harness/runs"
-triage_dir="$(dirname "$inbox_file")"
-run_file="$runs_dir/${safe_run_id}-heartbeat-triage.json"
-mkdir -p "$triage_dir" "$runs_dir"
-
-json_escape() {
-  local value="$1"
-  value="${value//\\/\\\\}"
-  value="${value//\"/\\\"}"
-  value="${value//$'\n'/\\n}"
-  value="${value//$'\r'/\\r}"
-  value="${value//$'\t'/\\t}"
-  printf '%s' "$value"
-}
-
-policy_get() {
-  local jq_path="$1"
-  local default_value="$2"
-
-  if [[ -f ".ai/harness/policy.json" ]] && command -v jq >/dev/null 2>&1; then
-    local value
-    value="$(jq -r "$jq_path // empty" ".ai/harness/policy.json" 2>/dev/null || true)"
-    if [[ -n "$value" ]]; then
-      printf '%s' "$value"
-      return 0
-    fi
-  fi
-
-  printf '%s' "$default_value"
-}
-
-helper_runtime_dir="$(policy_get '.harness.helper_runtime_dir' '.ai/harness/scripts')"
-
-helper_path() {
-  local helper_name="$1"
-
-  if [[ -f "$helper_runtime_dir/$helper_name" ]]; then
-    printf '%s/%s' "$helper_runtime_dir" "$helper_name"
-    return 0
-  fi
-
-  if [[ -f "scripts/$helper_name" ]]; then
-    printf '%s/%s' "scripts" "$helper_name"
-    return 0
-  fi
-
-  printf '%s/%s' "$helper_runtime_dir" "$helper_name"
-}
-
-repo_relative() {
-  local path="$1"
-  case "$path" in
-    "$repo"/*) printf '%s' "${path#"$repo"/}" ;;
-    "$repo") printf '.' ;;
-    *) printf '%s' "$path" ;;
-  esac
-}
-
-first_line() {
-  awk 'NF { print; exit }'
-}
-
-date_plus_14_days() {
-  if date -v+14d '+%Y-%m-%d' >/dev/null 2>&1; then
-    date -v+14d '+%Y-%m-%d'
-  elif date -d '+14 days' '+%Y-%m-%d' >/dev/null 2>&1; then
-    date -d '+14 days' '+%Y-%m-%d'
-  else
-    date '+%Y-%m-%d'
-  fi
-}
-
-entry_kinds=()
-entry_statuses=()
-entry_summaries=()
-entry_details=()
-
-add_entry() {
-  entry_kinds+=("$1")
-  entry_statuses+=("$2")
-  entry_summaries+=("$3")
-  entry_details+=("$4")
-}
-
-run_workflow_check() {
-  local output status summary
-  local check_script
-  check_script="$(helper_path "check-task-workflow.sh")"
-
-  if [[ ! -f "$check_script" ]]; then
-    add_entry "workflow-check" "warning" "$check_script is missing" ""
-    return 0
-  fi
-
-  set +e
-  output="$(bash "$check_script" --strict 2>&1)"
-  status=$?
-  set -e
-
-  if [[ "$status" -eq 0 ]]; then
-    add_entry "workflow-check" "pass" "check-task-workflow.sh --strict passed" "$output"
-  else
-    summary="$(printf '%s\n' "$output" | first_line)"
-    add_entry "workflow-check" "fail" "${summary:-check-task-workflow.sh --strict failed}" "$output"
-  fi
-}
-
-extract_next_pending_from_sprint() {
-  local sprint_file="$1"
-  awk -F '|' '
-    function trim(s) {
-      gsub(/^[[:space:]]+|[[:space:]]+$/, "", s)
-      return s
-    }
-    /^## Backlog[[:space:]]*$/ { in_section = 1; next }
-    in_section && /^## / { exit }
-    !in_section { next }
-    /^\|[[:space:]]*[0-9]+[[:space:]]*\|/ {
-      idx = trim($2)
-      status = trim($3)
-      task = trim($4)
-      mode = trim($5)
-      acceptance = trim($6)
-      plan = trim($7)
-      if (status == "[ ]") {
-        printf "index: %s\ntask: %s\nmode: %s\nacceptance: %s\nplan: %s\n", idx, task, mode, acceptance, plan
-        exit
-      }
-    }
-  ' "$sprint_file"
-}
-
-find_executing_sprint() {
-  local file status
-  local sprints_dir
-  sprints_dir="$(policy_get '.sprints.dir' 'plans/sprints')"
-  [[ -d "$sprints_dir" ]] || return 1
-  while IFS= read -r file; do
-    status="$(awk '/\*\*Status\*\*:/ { sub(/^.*\*\*Status\*\*: */, ""); gsub(/\r/, ""); print; exit }' "$file" | xargs)"
-    case "$status" in
-      Executing|Approved)
-        printf '%s\n' "$file"
-        return 0
-        ;;
-    esac
-  done < <(find "$sprints_dir" -maxdepth 1 -name '*.sprint.md' -type f | sort -r)
-  return 1
-}
-
-run_sprint_next() {
-  local output status summary sprint_file task
-  local sprint_helper
-  sprint_helper="$(helper_path "sprint-backlog.sh")"
-
-  if [[ -f ".ai/harness/sprint/active-sprint" && -f "$sprint_helper" ]]; then
-    set +e
-    output="$(bash "$sprint_helper" next 2>&1)"
-    status=$?
-    set -e
-    if [[ "$status" -eq 0 ]]; then
-      task="$(printf '%s\n' "$output" | awk -F ': ' '/^task:/ { print $2; exit }')"
-      add_entry "sprint-next" "action" "next sprint task: ${task:-unknown}" "$output"
-      return 0
-    fi
-    if [[ "$status" -eq 3 ]]; then
-      add_entry "sprint-next" "pass" "no pending sprint task" "$output"
-      return 0
-    fi
-  fi
-
-  if sprint_file="$(find_executing_sprint)"; then
-    output="$(extract_next_pending_from_sprint "$sprint_file")"
-    if [[ -n "$output" ]]; then
-      task="$(printf '%s\n' "$output" | awk -F ': ' '/^task:/ { print $2; exit }')"
-      add_entry "sprint-next" "action" "next sprint task: ${task:-unknown}" "$output"
-    else
-      add_entry "sprint-next" "pass" "no pending sprint task in $sprint_file" ""
-    fi
-  else
-    add_entry "sprint-next" "info" "no active or executing sprint found" ""
-  fi
-}
-
-run_drift_requests() {
-  local details count
-  if [[ ! -d "docs/architecture/requests" ]]; then
-    add_entry "drift-requests" "pass" "no architecture request directory" ""
-    return 0
-  fi
-
-  details="$(find docs/architecture/requests -maxdepth 1 -type f ! -name '.gitkeep' | sort)"
-  if [[ -z "$details" ]]; then
-    add_entry "drift-requests" "pass" "no pending architecture drift requests" ""
-    return 0
-  fi
-
-  count="$(printf '%s\n' "$details" | sed '/^$/d' | wc -l | xargs)"
-  add_entry "drift-requests" "action" "${count} pending architecture drift request(s)" "$details"
-}
-
-write_json_snapshot() {
-  local target="$1"
-  local idx
-  {
-    echo "{"
-    printf '  "version": 1,\n'
-    printf '  "kind": "forge-heartbeat-triage",\n'
-    printf '  "run_id": "%s",\n' "$(json_escape "$run_id")"
-    printf '  "source": "%s",\n' "$(json_escape "$run_source")"
-    printf '  "generated_at": "%s",\n' "$(json_escape "$timestamp")"
-    printf '  "repo": "%s",\n' "$(json_escape "$repo")"
-    printf '  "inbox": "%s",\n' "$(json_escape "$(repo_relative "$inbox_file")")"
-    printf '  "run_file": "%s",\n' "$(json_escape "$(repo_relative "$run_file")")"
-    printf '  "adoption_review_due": "%s",\n' "$(json_escape "$adoption_review_due")"
-    echo '  "entries": ['
-    for idx in "${!entry_kinds[@]}"; do
-      [[ "$idx" -eq 0 ]] || echo ","
-      printf '    {"kind":"%s","status":"%s","summary":"%s","details":"%s"}' \
-        "$(json_escape "${entry_kinds[$idx]}")" \
-        "$(json_escape "${entry_statuses[$idx]}")" \
-        "$(json_escape "${entry_summaries[$idx]}")" \
-        "$(json_escape "${entry_details[$idx]}")"
-    done
-    echo
-    echo '  ]'
-    echo "}"
-  } > "$target"
-}
-
-write_inbox() {
-  local idx detail_line
-  if [[ ! -f "$inbox_file" ]]; then
-    {
-      echo "# Heartbeat Triage Inbox"
-      echo
-      echo "<!-- managed by scripts/heartbeat-triage.sh; append-only run log -->"
-      echo
-    } > "$inbox_file"
-  fi
-
-  {
-    echo "## Run ${run_id} - ${timestamp}"
-    echo
-    echo "- Source: ${run_source}"
-    echo "- Run snapshot: $(repo_relative "$run_file")"
-    echo "- Adoption review due: ${adoption_review_due}"
-    echo
-    echo "### Entries"
-    echo
-    for idx in "${!entry_kinds[@]}"; do
-      printf -- "- [%s] %s: %s\n" "${entry_statuses[$idx]}" "${entry_kinds[$idx]}" "${entry_summaries[$idx]}"
-      if [[ -n "${entry_details[$idx]}" ]]; then
-        while IFS= read -r detail_line; do
-          [[ -n "$detail_line" ]] || continue
-          printf '  - %s\n' "$detail_line"
-        done <<< "${entry_details[$idx]}"
-      fi
-    done
-    echo
-  } >> "$inbox_file"
-}
-
-adoption_review_due="$(date_plus_14_days)"
-run_workflow_check
-run_sprint_next
-run_drift_requests
-write_json_snapshot "$run_file"
-write_inbox
-
-if [[ "$json_output" -eq 1 ]]; then
-  cat "$run_file"
-else
-  echo "[Heartbeat] wrote $(repo_relative "$inbox_file")"
-  echo "[Heartbeat] run snapshot: $(repo_relative "$run_file")"
-fi