@moretea-labs/forge 1.7.1 → 1.8.0

package/src/testing/test-governance.ts

@@ -10,8 +10,20 @@ import {
   writeFileSync,
 } from 'fs';
 import { dirname, join, relative, resolve } from 'path';
-import { runBunTestFile, TEST_FAILURE_CODES, type BunTestFileRunResult } from '../../scripts/run-bun-test-file';
-import { runBoundedChild } from '../runtime/shared/bounded-child-supervisor';
+import {
+  classifyTestSignal,
+  mapTestSupervisorFailure,
+  runBunTestFile,
+  TEST_FAILURE_CODES,
+  type BunTestFileRunResult,
+  type TestFailureClass,
+} from '../../scripts/run-bun-test-file';
+import { runBoundedChild, type BoundedChildRunResult } from '../runtime/shared/bounded-child-supervisor';
+import { ensureRepositoryCheckStorage, type RepositoryCheckStorageAuthority } from '../runtime/execution/process-runtime/check-storage';
+import {
+  MAX_STRUCTURED_CHECK_FAILURE_DETAILS,
+  type StructuredCheckFailureEvidence,
+} from '../runtime/execution/process-runtime/check-result';
 
 export const TEST_MODULES = [
   'core', 'controller', 'process-runtime', 'routing', 'repository',
@@ -57,8 +69,8 @@ export interface TestSelection {
 }
 
 const MANIFEST_PATH = 'tests/test-manifest.v1.json';
-const CHECKPOINT_ROOT = '.ai/harness/checks/tests/checkpoints';
-const RECEIPT_ROOT = '.ai/harness/checks/tests/receipts';
+const CHECKPOINT_SUBDIR = join('tests', 'checkpoints');
+const RECEIPT_SUBDIR = join('tests', 'receipts');
 const INFRASTRUCTURE_RESOURCES = new Set<TestResource>([
   'git-worktree', 'process-tree', 'fixed-port', 'runtime-singleton',
 ]);
@@ -375,10 +387,40 @@ async function runPool<T>(items: T[], concurrency: number, run: (item: T) => Pro
   }));
 }
 
+export interface TestRunReceipt {
+  version: 1;
+  gate: TestGate;
+  contentDigest: string;
+  runnerDigest: string;
+  status: 'passed' | 'failed';
+  selected: number;
+  cacheHits: number;
+  cacheProvenance: Array<Record<string, unknown>>;
+  failures: number;
+  failureEvidence: StructuredCheckFailureEvidence;
+  modules: TestModule[];
+  durationMs: number;
+  serialEquivalentMs: number;
+  serialReduction: number;
+  lanes: Record<string, number>;
+  completedAt: string;
+}
+
 export interface RunTestSelectionOptions {
   useCache?: boolean;
+  storageAuthority?: RepositoryCheckStorageAuthority;
   pureConcurrency?: number;
   tempConcurrency?: number;
+  onReceipt?: (receipt: TestRunReceipt) => void;
+}
+
+function classifyIndependentTestChild(result: BoundedChildRunResult): Pick<BunTestFileRunResult, 'failureClass' | 'failureCode' | 'signal'> {
+  const infrastructureFailure = mapTestSupervisorFailure(result.failureCode);
+  if (infrastructureFailure) return { failureClass: 'infrastructure', failureCode: infrastructureFailure };
+  const interrupted = classifyTestSignal(result.signal);
+  if (interrupted) return { ...interrupted, signal: result.signal ?? undefined };
+  if (result.status !== 0) return { failureClass: 'source', failureCode: TEST_FAILURE_CODES.SOURCE_ASSERTION_FAILED };
+  return {};
 }
 
 export async function runTestSelection(
@@ -388,6 +430,7 @@ export async function runTestSelection(
   options: RunTestSelectionOptions = {},
 ): Promise<number> {
   const useCache = options.useCache ?? true;
+  const storage = ensureRepositoryCheckStorage(repoRoot, options.storageAuthority);
   const baselineWorkspace = workspaceMutationDigest(repoRoot);
   const contentDigest = testContentDigest(repoRoot);
   const runnerDigest = hashFiles(repoRoot, [
@@ -402,6 +445,8 @@ export async function runTestSelection(
   const capability = capabilitySignature();
   let failures = 0;
   let cacheHits = 0;
+  const failureClasses = new Set<TestFailureClass>();
+  const failureDetails: StructuredCheckFailureEvidence['failureDetails'] = [];
   const cacheProvenance: Array<{
     file: string;
     checkpointKey: string;
@@ -425,12 +470,12 @@ export async function runTestSelection(
     const key = createHash('sha256').update(JSON.stringify({
       inputDigest, runnerDigest, testDigest, toolchain, capability, file,
     })).digest('hex');
-    const checkpointPath = join(repoRoot, CHECKPOINT_ROOT, `${key}.json`);
+    const checkpointPath = join(storage.physicalRoot, CHECKPOINT_SUBDIR, `${key}.json`);
     const cachedCheckpoint = useCache ? readPassedCheckpoint(checkpointPath, key) : undefined;
     if (cachedCheckpoint) {
       cacheHits += 1;
       serialEquivalentMs += cachedCheckpoint.durationMs;
-      const checkpointRelativePath = relative(repoRoot, checkpointPath).replace(/\\/g, '/');
+      const checkpointRelativePath = `controller-home://checks/${join(CHECKPOINT_SUBDIR, `${key}.json`).replace(/\\/g, '/')}`;
       cacheProvenance.push({
         file,
         checkpointKey: cachedCheckpoint.key,
@@ -465,15 +510,7 @@ export async function runTestSelection(
           lingeringPids: independent.residualPids,
           remainingPids: independent.remainingPids,
           pidReuseFenced: independent.pidReuseFenced,
-          ...(independent.failureCode ? {
-            failureClass: 'infrastructure' as const,
-            failureCode: independent.timedOut
-              ? TEST_FAILURE_CODES.INFRA_FILE_WALL_TIMEOUT
-              : TEST_FAILURE_CODES.INFRA_RUNNER_DID_NOT_CONVERGE,
-          } : independent.status === 0 ? {} : {
-            failureClass: 'source' as const,
-            failureCode: TEST_FAILURE_CODES.SOURCE_ASSERTION_FAILED,
-          }),
+          ...classifyIndependentTestChild(independent),
         };
       } else if (file.startsWith('tests/infrastructure/')) {
         const independent = await runBoundedChild(process.execPath, [
@@ -490,15 +527,7 @@ export async function runTestSelection(
           lingeringPids: independent.residualPids,
           remainingPids: independent.remainingPids,
           pidReuseFenced: independent.pidReuseFenced,
-          ...(independent.failureCode ? {
-            failureClass: 'infrastructure' as const,
-            failureCode: independent.timedOut
-              ? TEST_FAILURE_CODES.INFRA_FILE_WALL_TIMEOUT
-              : TEST_FAILURE_CODES.INFRA_RUNNER_DID_NOT_CONVERGE,
-          } : independent.status === 0 ? {} : {
-            failureClass: 'source' as const,
-            failureCode: TEST_FAILURE_CODES.SOURCE_ASSERTION_FAILED,
-          }),
+          ...classifyIndependentTestChild(independent),
         };
       } else {
         result = await runBunTestFile([
@@ -540,7 +569,22 @@ export async function runTestSelection(
     };
     atomicJson(checkpointPath, checkpoint);
     serialEquivalentMs += checkpoint.durationMs;
-    if (result.exitCode !== 0) failures += 1;
+    if (result.exitCode !== 0) {
+      failures += 1;
+      const failureClass = result.failureClass ?? 'infrastructure';
+      const failureCode = result.failureCode ?? TEST_FAILURE_CODES.INFRA_UNCLASSIFIED_NONZERO;
+      failureClasses.add(failureClass);
+      failureDetails.push({
+        file,
+        failureClass,
+        failureCode,
+        attempts,
+        durationMs: checkpoint.durationMs,
+        ...(result.signal ? { signal: result.signal } : {}),
+      });
+      failureDetails.sort((left, right) => left.file.localeCompare(right.file));
+      if (failureDetails.length > MAX_STRUCTURED_CHECK_FAILURE_DETAILS) failureDetails.pop();
+    }
   };
 
   const pure = selection.files.filter((file) => manifest.tests[file]!.resource === 'pure');
@@ -560,23 +604,39 @@ export async function runTestSelection(
     for (const file of files) await runOne(file);
   }));
 
-  if (workspaceMutationDigest(repoRoot) !== baselineWorkspace) contaminated = true;
+  if (workspaceMutationDigest(repoRoot) !== baselineWorkspace) {
+    contaminated = true;
+    failureClasses.add('infrastructure');
+  }
 
   const durationMs = Math.round(performance.now() - runStartedAt);
   const serialReduction = serialEquivalentMs > 0
     ? Math.max(0, 1 - (durationMs / serialEquivalentMs))
     : 0;
 
-  const receipt = {
+  const status = failures === 0 && !contaminated ? 'passed' as const : 'failed' as const;
+  const failureEvidence: StructuredCheckFailureEvidence = {
+    schemaVersion: 1,
+    producer: 'test-governance',
+    gate: selection.gate,
+    status,
+    failures,
+    failureClasses: [...failureClasses].sort(),
+    failureDetails: [...failureDetails],
+    failureDetailsTruncated: failures > failureDetails.length,
+    contaminated,
+  };
+  const receipt: TestRunReceipt = {
     version: 1,
     gate: selection.gate,
     contentDigest,
     runnerDigest,
-    status: failures === 0 && !contaminated ? 'passed' : 'failed',
+    status,
     selected: selection.files.length,
     cacheHits,
     cacheProvenance: cacheProvenance.sort((left, right) => left.file.localeCompare(right.file)),
     failures,
+    failureEvidence,
     modules: selection.modules,
     durationMs,
     serialEquivalentMs,
@@ -588,7 +648,8 @@ export async function runTestSelection(
     ]),
     completedAt: new Date().toISOString(),
   };
-  atomicJson(join(repoRoot, RECEIPT_ROOT, `${contentDigest}-${selection.gate}.json`), receipt);
+  atomicJson(join(storage.physicalRoot, RECEIPT_SUBDIR, `${contentDigest}-${selection.gate}.json`), receipt);
+  options.onReceipt?.(receipt);
   console.error(`[tests] ${receipt.status}: ${selection.files.length} selected, ${cacheHits} checkpoint hit(s), ${failures} failure(s), ${(serialReduction * 100).toFixed(1)}% vs serial`);
   return receipt.status === 'passed' ? 0 : 1;
 }

package/assets/templates/helpers/archive-architecture-request.sh

@@ -1,244 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-usage() {
-  cat <<'USAGE_EOF'
-Usage:
-  scripts/archive-architecture-request.sh --request <docs/architecture/requests/file.md> --status <resolved|superseded|rejected|no-change> [--artifact <path>] [--note <text>]
-
-Archives a handled architecture drift request without making semantic architecture decisions.
-USAGE_EOF
-}
-
-repo="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-repo="$(cd "$repo" && pwd)"
-cd "$repo"
-
-request_file=""
-status=""
-note=""
-artifacts=()
-
-safe_token() {
-  local value="$1"
-  value="$(printf '%s' "$value" | tr '[:upper:]' '[:lower:]')"
-  value="$(printf '%s' "$value" | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
-  printf '%s' "${value:-request}"
-}
-
-repo_relative_path() {
-  local value="$1"
-  value="${value#file://}"
-  case "$value" in
-    "$repo"/*)
-      value="${value#$repo/}"
-      ;;
-    /*)
-      return 1
-      ;;
-    ./*)
-      value="${value#./}"
-      ;;
-  esac
-
-  case "$value" in
-    ""|.|..|../*|*/../*|*$'\n'*|*$'\r'*)
-      return 1
-      ;;
-  esac
-
-  printf '%s' "$value"
-}
-
-canonical_status() {
-  case "$(safe_token "$1")" in
-    resolved)
-      printf 'Resolved'
-      ;;
-    superseded)
-      printf 'Superseded'
-      ;;
-    rejected)
-      printf 'Rejected'
-      ;;
-    no-change|no-architecture-change|no-arch-change)
-      printf 'No architecture change'
-      ;;
-    *)
-      return 1
-      ;;
-  esac
-}
-
-clear_contract_pending_request() {
-  local rel_request="$1"
-  local short_request="${rel_request#docs/architecture/}"
-  local file tmp
-
-  find . \
-    \( -path './.git' -o -path './node_modules' -o -path './_ref' -o -path './_ops' \) -prune -o \
-    \( -name 'AGENTS.md' -o -name 'CLAUDE.md' \) -type f -print 2>/dev/null |
-    while IFS= read -r file; do
-      if ! grep -Fq "Pending architecture request: \`${rel_request}\`" "$file" &&
-         ! grep -Fq "Pending architecture request: \`${short_request}\`" "$file"; then
-        continue
-      fi
-      tmp="$(mktemp)" || continue
-      awk -v rel="$rel_request" -v short="$short_request" '
-        index($0, "Pending architecture request: `" rel "`") > 0 ||
-        index($0, "Pending architecture request: `" short "`") > 0 {
-          print "- Pending architecture request: `(none)`"
-          next
-        }
-        { print }
-      ' "$file" > "$tmp"
-      mv "$tmp" "$file"
-      echo "[ArchitectureArchive] Cleared pending architecture request in ${file#./}"
-    done
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --request)
-      [[ -n "${2:-}" ]] || { echo "archive-architecture-request: --request requires a value" >&2; exit 2; }
-      request_file="$2"
-      shift 2
-      ;;
-    --status)
-      [[ -n "${2:-}" ]] || { echo "archive-architecture-request: --status requires a value" >&2; exit 2; }
-      status="$2"
-      shift 2
-      ;;
-    --artifact)
-      [[ -n "${2:-}" ]] || { echo "archive-architecture-request: --artifact requires a value" >&2; exit 2; }
-      artifacts+=("$2")
-      shift 2
-      ;;
-    --note)
-      [[ -n "${2:-}" ]] || { echo "archive-architecture-request: --note requires a value" >&2; exit 2; }
-      note="$2"
-      shift 2
-      ;;
-    --help|-h)
-      usage
-      exit 0
-      ;;
-    *)
-      echo "archive-architecture-request: unknown argument: $1" >&2
-      usage
-      exit 2
-      ;;
-  esac
-done
-
-if [[ -z "$request_file" || -z "$status" ]]; then
-  usage >&2
-  exit 2
-fi
-
-rel_request="$(repo_relative_path "$request_file" || true)"
-if [[ -z "$rel_request" ]]; then
-  echo "archive-architecture-request: unsafe request path: $request_file" >&2
-  exit 2
-fi
-
-case "$rel_request" in
-  docs/architecture/requests/*.md)
-    ;;
-  *)
-    echo "archive-architecture-request: request must be under docs/architecture/requests/: $rel_request" >&2
-    exit 2
-    ;;
-esac
-
-case "$rel_request" in
-  docs/architecture/requests/archive/*)
-    echo "archive-architecture-request: request is already archived: $rel_request" >&2
-    exit 2
-    ;;
-esac
-
-if [[ ! -f "$rel_request" ]]; then
-  echo "archive-architecture-request: request not found: $rel_request" >&2
-  exit 1
-fi
-
-resolved_status="$(canonical_status "$status" || true)"
-if [[ -z "$resolved_status" ]]; then
-  echo "archive-architecture-request: unsupported status: $status" >&2
-  usage >&2
-  exit 2
-fi
-
-artifact_lines=()
-if [[ "${#artifacts[@]}" -gt 0 ]]; then
-  for artifact in "${artifacts[@]-}"; do
-    [[ -n "$artifact" ]] || continue
-    rel_artifact="$(repo_relative_path "$artifact" || true)"
-    if [[ -z "$rel_artifact" ]]; then
-      echo "archive-architecture-request: unsafe artifact path: $artifact" >&2
-      exit 2
-    fi
-    artifact_lines+=("- \`${rel_artifact}\`")
-  done
-fi
-
-archive_year="$(date '+%Y')"
-archive_dir="docs/architecture/requests/archive/${archive_year}"
-archive_file="${archive_dir}/$(basename "$rel_request")"
-if [[ -e "$archive_file" ]]; then
-  archive_file="${archive_dir}/$(date '+%Y%m%d-%H%M%S')-$(basename "$rel_request")"
-fi
-
-mkdir -p "$archive_dir"
-
-tmp_file="$(mktemp)"
-awk -v status="$resolved_status" '
-  BEGIN { replaced = 0 }
-  /^\> \*\*Status\*\*:/ {
-    print "> **Status**: " status
-    replaced = 1
-    next
-  }
-  { print }
-  END {
-    if (replaced == 0) {
-      print ""
-      print "> **Status**: " status
-    }
-  }
-' "$rel_request" > "$tmp_file"
-
-{
-  echo ""
-  echo "## Archive Resolution"
-  echo ""
-  echo "- Status: ${resolved_status}"
-  echo "- Archived: $(date '+%Y-%m-%dT%H:%M:%S%z')"
-  if [[ "${#artifact_lines[@]}" -gt 0 ]]; then
-    echo "- Artifacts:"
-    printf '%s\n' "${artifact_lines[@]}"
-  else
-    echo "- Artifacts: (none)"
-  fi
-  if [[ -n "$note" ]]; then
-    echo "- Note: ${note}"
-  fi
-} >> "$tmp_file"
-
-mv "$tmp_file" "$archive_file"
-rm -f "$rel_request"
-
-index_file="docs/architecture/index.md"
-if [[ -f "$index_file" ]]; then
-  index_tmp="$(mktemp)"
-  awk -v rel="$rel_request" -v short="${rel_request#docs/architecture/}" '
-    index($0, rel) == 0 && index($0, short) == 0 { print }
-  ' "$index_file" > "$index_tmp"
-  mv "$index_tmp" "$index_file"
-fi
-
-clear_contract_pending_request "$rel_request"
-
-echo "[ArchitectureArchive] Archived ${rel_request} -> ${archive_file}"
-echo "[ArchitectureArchive] status=${resolved_status}"

package/docs/architecture/history/README.md

@@ -1,7 +0,0 @@
-# Architecture History Archive
-
-Status: **Historical Evidence — Not Runtime Authority**
-
-The current Forge architecture contract is [`../CURRENT.md`](../CURRENT.md). Files in this directory preserve superseded design rationale or timestamped operational evidence and may intentionally contain old product names, machine-specific paths, historical phase/status labels, or assumptions that no longer hold.
-
-Do not update an archived page to make it look current. Fold any still-valid invariant into `CURRENT.md`, keep accepted rationale in an ADR when appropriate, and leave execution state in durable Plan/Work/evidence records.