@moretea-labs/forge 1.6.0 → 1.7.0

package/assets/templates/helpers/verify-contract.sh

@@ -69,24 +69,6 @@ read_contract_status() {
   awk '/^> \*\*Status\*\*:/ {sub(/^.*> \*\*Status\*\*: */, ""); gsub(/\r/, ""); print; exit}' "$file" | xargs
 }
 
-read_contract_review_file() {
-  local file="$1"
-  local line=""
-  local value=""
-
-  line="$(grep -m 1 -E '^> \*\*Review File\*\*:' "$file" || true)"
-  [[ -n "$line" ]] || return 0
-
-  if [[ "$line" == *\`* ]]; then
-    value="${line#*\`}"
-    value="${value%%\`*}"
-  else
-    value="${line#*> **Review File**:}"
-  fi
-
-  printf '%s' "$value" | tr -d '\r' | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//'
-}
-
 read_contract_task_profile() {
   local file="$1"
   awk '/^> \*\*Task Profile\*\*:/ {sub(/^.*> \*\*Task Profile\*\*:[[:space:]]*/, ""); gsub(/\r/, ""); print; exit}' "$file" | xargs
@@ -130,36 +112,6 @@ contract_allowed_paths() {
   '
 }
 
-review_recommends_pass() {
-  local review_file="$1"
-  [[ -n "$review_file" && -f "$review_file" ]] || return 1
-  grep -Eq '^> \*\*Recommendation\*\*:[[:space:]]*pass[[:space:]]*$' "$review_file"
-}
-
-review_score() {
-  local review_file="$1"
-  local dimension="$2"
-
-  [[ -n "$review_file" && -f "$review_file" ]] || return 1
-
-  awk -F'|' -v wanted="$dimension" '
-    function trim(s) {
-      gsub(/^[[:space:]]+/, "", s)
-      gsub(/[[:space:]]+$/, "", s)
-      return s
-    }
-    BEGIN { wanted = tolower(wanted) }
-    /^\|/ {
-      dim = tolower(trim($2))
-      score = trim($3)
-      if (dim == wanted && match(score, /[0-9]+/)) {
-        print substr(score, RSTART, RLENGTH)
-        exit
-      }
-    }
-  ' "$review_file"
-}
-
 update_contract_status() {
   local file="$1"
   local status="$2"
@@ -385,14 +337,9 @@ declare -a contain_patterns=()
 declare -a files_not_exist=()
 declare -a not_contain_paths=()
 declare -a not_contain_patterns=()
-declare -a qa_dimensions=()
-declare -a qa_mins=()
-declare -a manual_checks=()
 
 section=""
 pending_path=""
-pending_dimension=""
-review_file="$(read_contract_review_file "$contract_file" || true)"
 task_profile="$(read_contract_task_profile "$contract_file" || true)"
 declare -a allowed_paths=()
 while IFS= read -r allowed_path; do
@@ -443,21 +390,10 @@ while IFS= read -r raw_line; do
       pending_path=""
       continue
       ;;
-    qa_scores:)
-      section="qa_scores"
-      pending_path=""
-      pending_dimension=""
-      continue
-      ;;
-    manual_checks:)
-      section="manual_checks"
-      pending_path=""
-      continue
-      ;;
   esac
 
   case "$section" in
-    files_exist|commands_succeed|files_not_exist|artifacts_exist|manual_checks)
+    files_exist|commands_succeed|files_not_exist|artifacts_exist)
       if [[ "$trimmed" =~ ^-[[:space:]]*(.+)$ ]]; then
         item="$(strip_quotes "${BASH_REMATCH[1]}")"
         [[ -n "$item" ]] || continue
@@ -467,8 +403,6 @@ while IFS= read -r raw_line; do
           commands_succeed+=("$item")
         elif [[ "$section" == "artifacts_exist" ]]; then
           artifacts_exist+=("$item")
-        elif [[ "$section" == "manual_checks" ]]; then
-          manual_checks+=("$item")
         else
           files_not_exist+=("$item")
         fi
@@ -497,19 +431,6 @@ while IFS= read -r raw_line; do
         fi
       fi
       ;;
-    qa_scores)
-      if [[ "$trimmed" =~ ^-[[:space:]]*dimension:[[:space:]]*(.+)$ ]]; then
-        pending_dimension="$(strip_quotes "${BASH_REMATCH[1]}")"
-      elif [[ "$trimmed" =~ ^dimension:[[:space:]]*(.+)$ ]]; then
-        pending_dimension="$(strip_quotes "${BASH_REMATCH[1]}")"
-      elif [[ "$trimmed" =~ ^min:[[:space:]]*([0-9]+)$ ]]; then
-        if [[ -n "$pending_dimension" ]]; then
-          qa_dimensions+=("$pending_dimension")
-          qa_mins+=("${BASH_REMATCH[1]}")
-          pending_dimension=""
-        fi
-      fi
-      ;;
   esac
 done <<< "$yaml_block"
 if ((${#tests_pass[@]} || ${#commands_succeed[@]})); then
@@ -602,37 +523,6 @@ if ((${#commands_succeed[@]})); then
   done
 fi
 
-if ((${#qa_dimensions[@]})); then
-  for idx in "${!qa_dimensions[@]}"; do
-    dimension="${qa_dimensions[$idx]}"
-    min_score="${qa_mins[$idx]}"
-    score="$(review_score "$review_file" "$dimension" || true)"
-
-    if [[ "$score" =~ ^[0-9]+$ && "$score" -ge "$min_score" ]]; then
-      pass "qa_scores" "$dimension" "qa_scores: $dimension ${score}/${min_score}"
-    else
-      fail "qa_scores" "$dimension" "qa_scores: $dimension score ${score:-missing} < $min_score"
-    fi
-  done
-fi
-
-if ((${#manual_checks[@]})); then
-  for check in "${manual_checks[@]}"; do
-    case "$check" in
-      "Evaluator review file recommends pass")
-        if review_recommends_pass "$review_file"; then
-          pass "manual_checks" "$check" "manual_checks: $check"
-        else
-          fail "manual_checks" "$check" "manual_checks: $check"
-        fi
-        ;;
-      *)
-        fail "manual_checks" "$check" "manual_checks unsupported: $check"
-        ;;
-    esac
-  done
-fi
-
 if ((${#contain_paths[@]})); then
   for idx in "${!contain_paths[@]}"; do
     path="${contain_paths[$idx]}"

package/assets/templates/helpers/verify-sprint.sh

@@ -20,54 +20,6 @@ json_escape() {
   printf '%s' "$value"
 }
 
-review_card_field() {
-  local file="$1"
-  local label="$2"
-  [[ -n "$file" && -f "$file" ]] || return 1
-  awk -v wanted="$label" '
-    function trim(s) {
-      gsub(/^[[:space:]]+/, "", s)
-      gsub(/[[:space:]]+$/, "", s)
-      return s
-    }
-    BEGIN { wanted = tolower(wanted) }
-    /^##[[:space:]]+Human Review Card[[:space:]]*$/ { in_section = 1; next }
-    in_section && /^##[[:space:]]+/ { exit }
-    !in_section { next }
-    /^[[:space:]]*-[[:space:]]*/ {
-      line = $0
-      sub(/^[[:space:]]*-[[:space:]]*/, "", line)
-      key = line
-      sub(/:.*/, "", key)
-      key = tolower(trim(key))
-      if (key == wanted) {
-        sub(/^[^:]*:[[:space:]]*/, "", line)
-        print trim(line)
-        exit
-      }
-    }
-  ' "$file"
-}
-
-normalize_status_token() {
-  local value="$1"
-  value="$(printf '%s' "$value" | sed -E 's/[;,].*$//; s/[[:space:]].*$//; s/^[[:space:]]+//; s/[[:space:]]+$//' | tr '[:upper:]' '[:lower:]')"
-  printf '%s' "$value"
-}
-
-field_has_concrete_value() {
-  local value="$1"
-  local token
-  token="$(normalize_status_token "$value")"
-  [[ -n "$token" ]] || return 1
-  case "$token" in
-    tbd|todo|n/a|na|none|unknown|unavailable|pending|...)
-      return 1
-      ;;
-  esac
-  return 0
-}
-
 read_contract_task_profile() {
   local file="$1"
   awk '/^> \*\*Task Profile\*\*:/ {sub(/^.*> \*\*Task Profile\*\*:[[:space:]]*/, ""); gsub(/\r/, ""); print; exit}' "$file" | xargs
@@ -304,25 +256,14 @@ if [[ -f ".ai/hooks/lib/workflow-state.sh" ]]; then
   # shellcheck source=/dev/null
   . ".ai/hooks/lib/workflow-state.sh"
   contract_file="$(workflow_active_contract || true)"
-  review_file="$(workflow_active_review || true)"
   checks_file="$(workflow_checks_file)"
 else
   contract_file="$(find tasks/contracts -maxdepth 1 -name '*.contract.md' -type f 2>/dev/null | sort | head -n 1)"
-  if [[ -n "$contract_file" ]]; then
-    contract_slug="$(basename "$contract_file" | sed -E 's/\.contract\.md$//')"
-    review_file="tasks/reviews/${contract_slug}.review.md"
-  else
-    review_file=""
-  fi
   checks_file=".ai/harness/checks/latest.json"
 fi
 if [[ -z "$contract_file" || ! -f "$contract_file" ]]; then
   contract_file="$(active_plan_declared_path "Task Contract" || active_plan_declared_path "Sprint Contract" || true)"
 fi
-if [[ -z "$review_file" || ! -f "$review_file" ]]; then
-  review_file="$(active_plan_declared_path "Task Review" || active_plan_declared_path "Sprint Review" || true)"
-fi
-
 [[ -n "$contract_file" && -f "$contract_file" ]] || { echo "No active sprint contract found" >&2; exit 1; }
 
 generated_at="$(date '+%Y-%m-%dT%H:%M:%S%z')"
@@ -378,74 +319,9 @@ if [[ -n "$contract_output" ]]; then
   printf '%s\n' "$contract_output"
 fi
 
-review_status="fail"
-review_message="Task review recommends pass and Human Review Card verdict is pass."
-review_card_verdict=""
-review_card_external=""
-review_card_change_type=""
-review_card_rollback=""
-if [[ -z "$review_file" || ! -f "$review_file" ]]; then
-  review_message="Missing task review file."
-  echo "Missing task review file" >&2
-else
-  review_card_verdict="$(normalize_status_token "$(review_card_field "$review_file" "Verdict" || true)")"
-  review_card_external="$(review_card_field "$review_file" "External acceptance" || true)"
-  review_card_change_type="$(normalize_status_token "$(review_card_field "$review_file" "Change type" || true)")"
-  review_card_rollback="$(review_card_field "$review_file" "Rollback" || true)"
-fi
-
-if [[ -n "$review_file" && -f "$review_file" ]]; then
-  if ! grep -Eq '^> \*\*Recommendation\*\*:[[:space:]]*pass([[:space:]]*)$' "$review_file"; then
-    review_message="Task review does not recommend pass."
-    echo "Task review does not recommend pass" >&2
-  elif [[ -z "$review_card_verdict" ]]; then
-    review_message="Task review is missing Human Review Card verdict."
-    echo "Task review is missing Human Review Card verdict" >&2
-  elif [[ "$review_card_verdict" != "pass" ]]; then
-    review_message="Human Review Card verdict is not pass: $review_card_verdict"
-    echo "Human Review Card verdict is not pass: $review_card_verdict" >&2
-  elif [[ -n "$task_profile" && "$review_card_change_type" != "$task_profile" ]]; then
-    review_message="Human Review Card change type does not match task_profile: ${review_card_change_type:-missing} != $task_profile"
-    echo "$review_message" >&2
-  elif ! field_has_concrete_value "$review_card_rollback"; then
-    review_message="Human Review Card rollback is missing or not concrete."
-    echo "$review_message" >&2
-  else
-    review_status="pass"
-  fi
-fi
-
-external_status="missing"
-external_reviewer=""
-external_source=""
-external_message="External acceptance status is unavailable."
-if declare -F workflow_external_acceptance_status >/dev/null 2>&1; then
-  external_row="$(workflow_external_acceptance_status "$review_file")"
-  IFS=$'\t' read -r external_status external_reviewer external_source external_message <<< "$external_row"
-fi
-card_external_status="$(normalize_status_token "$review_card_external")"
-case "$external_status" in
-  missing|unavailable|"")
-    case "$card_external_status" in
-      pass|manual_override|not_required)
-        external_status="$card_external_status"
-        external_message="Human Review Card external acceptance: $review_card_external"
-        ;;
-    esac
-    ;;
-esac
-
 status="fail"
 exit_code=1
-case "$external_status" in
-  pass|manual_override|not_required)
-    external_gate="pass"
-    ;;
-  *)
-    external_gate="fail"
-    ;;
-esac
-if [[ "$contract_exit" -eq 0 && "$review_status" == "pass" && "$external_gate" == "pass" && "$allowed_paths_status" == "pass" ]]; then
+if [[ "$contract_exit" -eq 0 && "$allowed_paths_status" == "pass" ]]; then
   status="pass"
   exit_code=0
 fi
@@ -456,10 +332,6 @@ fi
 if [[ -z "$failure_class" && "$status" != "pass" ]]; then
   if [[ "$contract_exit" -ne 0 ]]; then
     failure_class="contract"
-  elif [[ "$review_status" != "pass" ]]; then
-    failure_class="review"
-  elif [[ "$external_gate" != "pass" ]]; then
-    failure_class="external_acceptance"
   elif [[ "$allowed_paths_status" != "pass" ]]; then
     failure_class="allowed_paths"
   else
@@ -467,9 +339,9 @@ if [[ -z "$failure_class" && "$status" != "pass" ]]; then
   fi
 fi
 if [[ "$status" == "pass" ]]; then
-  next_step="finish contract worktree or archive completed task"
+  next_step="perform a fresh semantic impact review, then finish contract worktree or archive completed task"
 else
-  next_step="resolve failing contract, review, external acceptance, or allowed_paths gate"
+  next_step="resolve failing contract or allowed_paths evidence"
 fi
 handoff_current_exists=false
 handoff_resume_exists=false
@@ -492,17 +364,6 @@ if command -v jq >/dev/null 2>&1 && jq -e . "$contract_report" >/dev/null 2>&1;
     --arg contract_status "$([[ "$contract_exit" -eq 0 ]] && printf pass || printf fail)" \
     --arg contract_command "$contract_command" \
     --argjson contract_exit "$contract_exit" \
-    --arg review_file "${review_file:-}" \
-    --arg review_status "$review_status" \
-    --arg review_message "$review_message" \
-    --arg review_card_verdict "$review_card_verdict" \
-    --arg review_card_change_type "$review_card_change_type" \
-    --arg review_card_external "$review_card_external" \
-    --arg review_card_rollback "$review_card_rollback" \
-    --arg external_status "$external_status" \
-    --arg external_reviewer "$external_reviewer" \
-    --arg external_source "$external_source" \
-    --arg external_message "$external_message" \
     --arg worktree "$worktree_path" \
     --arg branch "$branch_name" \
     --arg diff_base_ref "$diff_base_ref" \
@@ -538,8 +399,6 @@ if command -v jq >/dev/null 2>&1 && jq -e . "$contract_report" >/dev/null 2>&1;
       ],
       guards: [
         {name: "contract", status: $contract_status},
-        {name: "review", status: $review_status},
-        {name: "external_acceptance", status: $external_status},
         {name: "allowed_paths", status: ($allowed_paths_check.status // "unavailable")}
       ],
       handoffs: [
@@ -563,23 +422,6 @@ if command -v jq >/dev/null 2>&1 && jq -e . "$contract_report" >/dev/null 2>&1;
         report: ($contract_report[0] // {}),
         task_profile: $task_profile,
         allowed_paths: $allowed_paths
-      },
-      review: {
-        file: $review_file,
-        status: $review_status,
-        message: $review_message,
-        card: {
-          verdict: $review_card_verdict,
-          change_type: $review_card_change_type,
-          external_acceptance: $review_card_external,
-          rollback: $review_card_rollback
-        }
-      },
-      external_acceptance: {
-        status: $external_status,
-        reviewer: $external_reviewer,
-        source: $external_source,
-        message: $external_message
       }
     }' > "$checks_report"
 else
@@ -617,8 +459,6 @@ else
   ],
   "guards": [
     {"name": "contract", "status": "$([[ "$contract_exit" -eq 0 ]] && printf pass || printf fail)"},
-    {"name": "review", "status": "$(json_escape "$review_status")"},
-    {"name": "external_acceptance", "status": "$(json_escape "$external_status")"},
     {"name": "allowed_paths", "status": "$(json_escape "$allowed_paths_status")"}
   ],
   "handoffs": [
@@ -644,23 +484,6 @@ else
     "exit_code": $contract_exit,
     "task_profile": "$(json_escape "$task_profile")",
     "allowed_paths": []
-  },
-  "review": {
-    "file": "$(json_escape "${review_file:-}")",
-    "status": "$(json_escape "$review_status")",
-    "message": "$(json_escape "$review_message")",
-    "card": {
-      "verdict": "$(json_escape "$review_card_verdict")",
-      "change_type": "$(json_escape "$review_card_change_type")",
-      "external_acceptance": "$(json_escape "$review_card_external")",
-      "rollback": "$(json_escape "$review_card_rollback")"
-    }
-  },
-  "external_acceptance": {
-    "status": "$(json_escape "$external_status")",
-    "reviewer": "$(json_escape "$external_reviewer")",
-    "source": "$(json_escape "$external_source")",
-    "message": "$(json_escape "$external_message")"
   }
 }
 EOF_CHECKS

package/assets/templates/plan.template.md

@@ -66,7 +66,7 @@ Complete this inventory before implementation. If any line is unknown, keep the
 
 - **State/progress path**:
 - **Verification evidence**:
-- **Evaluator rubric**:
+- **Impact review**:
 - **Stop condition**:
 - **Rollback surface**:
 

package/assets/templates/review.template.md

@@ -6,19 +6,15 @@
 > **Notes File**: {{NOTES_FILE}}
 > **Checks File**: {{CHECKS_FILE}}
 > **Last Updated**: {{TIMESTAMP}}
-> **Recommendation**: fail
+> **Summary**:
 
-## Human Review Card
+## Semantic Impact Review
 
-- Verdict: pending
-- Change type: code-change | docs-only | ledger-closeout | migration | eval-only | delegated-run
-- Intended files changed:
-- Actual files changed:
-- Commands passed:
-- External acceptance: unavailable
-- Residual risks:
-- Reviewer action required: inspect diff and card
-- Rollback:
+- User intent:
+- Affected domains and downstream consumers:
+- State transitions and persistence/restart impact:
+- Missing impact areas or uncertainty:
+- Residual risks and recovery:
 
 ## Mode Evidence
 
@@ -28,26 +24,14 @@
 
 ## Verification Evidence
 
-- Waza `/check` run:
+- Focused/full checks:
 - Commands run:
 - Manual checks:
 - Supporting artifacts:
 - Implementation notes reviewed:
 - Run snapshot:
 
-## External Acceptance Advice
-
-> **External Acceptance**: unavailable
-> **External Reviewer**:
-> **External Source**:
-> **External Started**:
-> **External Completed**:
-
-- P1 blockers:
-- P2 advisories:
-- Acceptance checklist:
-
-## Behavior Diff Notes
+## Scenario Evidence
 
 - ...
 
@@ -55,15 +39,6 @@
 
 - ...
 
-## Scorecard
-
-| Dimension | Score | Notes |
-|-----------|-------|-------|
-| Functionality | 0/10 | |
-| Product depth | 0/10 | |
-| Design quality | 0/10 | |
-| Code quality | 0/10 | |
-
 ## Failing Items
 
 - ...

package/assets/workflow-contract.v1.json

@@ -99,7 +99,6 @@
       "verify-contract.sh",
       "summarize-failures.sh",
       "verify-sprint.sh",
-      "harness-trace-grade.sh",
       "sprint-backlog.sh",
       "check-task-sync.sh",
       "check-deploy-sql-order.sh",
@@ -112,8 +111,6 @@
       "select-agent-context-blocks.sh",
       "ensure-task-workflow.sh",
       "check-task-workflow.sh",
-      "maintenance-triage.sh",
-      "heartbeat-triage.sh",
       "switch-plan.sh",
       "workflow-contract.ts",
       "inspect-project-state.ts",
@@ -164,7 +161,6 @@
       ".ai/harness/local-jobs",
       ".ai/harness/controller",
       ".ai/harness/edit-sessions",
-      ".ai/harness/triage",
       "docs/architecture",
       "docs/architecture/domains",
       "docs/architecture/modules",
@@ -204,7 +200,6 @@
       "scripts/verify-contract.sh",
       "scripts/summarize-failures.sh",
       "scripts/verify-sprint.sh",
-      "scripts/harness-trace-grade.sh",
       "scripts/sprint-backlog.sh",
       "scripts/check-task-sync.sh",
       "scripts/check-deploy-sql-order.sh",
@@ -216,8 +211,6 @@
       "scripts/select-agent-context-blocks.sh",
       "scripts/ensure-task-workflow.sh",
       "scripts/check-task-workflow.sh",
-      "scripts/maintenance-triage.sh",
-      "scripts/heartbeat-triage.sh",
       "scripts/switch-plan.sh",
       "scripts/workflow-contract.ts",
       "scripts/inspect-project-state.ts",
@@ -246,7 +239,6 @@
       "docs/reference-configs/agentic-development-flow.md",
       "docs/reference-configs/external-tooling.md",
       "docs/reference-configs/sprint-contracts.md",
-      "docs/reference-configs/heartbeat-triage.md",
       "docs/reference-configs/handoff-protocol.md",
       "docs/reference-configs/document-generation.md",
       "docs/reference-configs/global-working-rules.md",
@@ -271,9 +263,7 @@
       ".ai/harness/worktrees/",
       ".ai/harness/runs/.gitkeep",
       ".ai/harness/local-jobs/",
-      ".ai/harness/controller/",
-      ".ai/harness/triage/.gitkeep",
-      ".ai/harness/triage/inbox.md"
+      ".ai/harness/controller/"
     ]
   },
   "documents": {
@@ -519,15 +509,16 @@
             "scripts/check-context-files.sh",
             "scripts/check-deploy-sql-order.sh",
             "scripts/check-skill-version.ts",
-            "scripts/check-task-sync.sh",
-            "scripts/check-task-workflow.sh",
-            "scripts/codex-handoff-resume.sh",
+        "scripts/check-task-sync.sh",
+        "scripts/check-task-workflow.sh",
+        "scripts/harness-trace-grade.sh",
+        "scripts/codex-handoff-resume.sh",
             "scripts/context-contract-sync.sh",
-            "scripts/contract-run.ts",
-            "scripts/contract-worktree.sh",
-            "scripts/ensure-task-workflow.sh",
-            "scripts/heartbeat-triage.sh",
-            "scripts/inspect-project-state.ts",
+        "scripts/contract-run.ts",
+        "scripts/contract-worktree.sh",
+        "scripts/ensure-task-workflow.sh",
+        "scripts/heartbeat-triage.sh",
+        "scripts/inspect-project-state.ts",
             "scripts/maintenance-triage.sh",
             "scripts/migrate-project-template.sh",
             "scripts/migrate-workflow-docs.ts",

package/docs/README.md

@@ -1,6 +1,6 @@
 # Forge Documentation
 
-> Maintained documentation for the current Forge product and runtime. Executable behavior and [`architecture/current/`](architecture/current/) are authoritative; historical notes are context, not active contracts.
+> Maintained documentation for the current Forge product and runtime. Executable behavior and [`architecture/CURRENT.md`](architecture/CURRENT.md) are authoritative for implementation facts and architecture contracts; historical notes are context, not active contracts.
 
 [中文文档中心](README.zh-CN.md) · [GitHub](https://github.com/moretea-labs/forge) · [Releases](https://github.com/moretea-labs/forge/releases) · [Support](../SUPPORT.md)
 
@@ -11,8 +11,8 @@
 | Install Forge | [Install and start](tutorials/01-install-and-start.md) | [Platform support](operations/platform-support.md) |
 | Connect ChatGPT | [Connect ChatGPT](tutorials/02-connect-chatgpt.md) | [MCP setup](forge-chatgpt-mcp-setup.md) |
 | Complete a first task | [First repository task](tutorials/03-first-repository-task.md) | [Public usage guide](public-usage-guide.md) |
-| Install an official provider | [Plugin management](forge-plugin-management.md) | [Provider configuration](operations/provider-configuration.md) |
-| Understand Forge | [Core Concepts](wiki/Core-Concepts.md) | [Architecture](wiki/Architecture.md) |
+| Install an official provider | [Plugin management](forge-plugin-management.md) | [Plugin management](forge-plugin-management.md) |
+| Understand Forge | [Current architecture](architecture/CURRENT.md) | [Roadmap](ROADMAP.md) |
 | Operate or recover | [Operations](wiki/Operations.md) | [Troubleshooting](operations/troubleshooting.md) |
 | Contribute or release | [Contributing](../CONTRIBUTING.md) | [Release process](operations/releasing.md) |
 
@@ -31,15 +31,14 @@ Forge is Direct-first: investigation does not create durable Work by itself, and
 - [Platform support](operations/platform-support.md)
 
 ### Understand
+- [Current architecture](architecture/CURRENT.md)
+- [Roadmap](ROADMAP.md)
+- [Architecture evolution](architecture/EVOLUTION.md)
+- [Version architecture snapshots](architecture/versions/)
 - [Core Concepts](wiki/Core-Concepts.md)
-- [Architecture](wiki/Architecture.md)
-- [Runtime Architecture](wiki/Runtime-Architecture.md)
-- [Work Lifecycle](wiki/Work-Lifecycle.md)
-- [Implementation map](wiki/Implementation.md)
 
 ### Integrate
 - [Plugin management](forge-plugin-management.md)
-- [Provider configuration](operations/provider-configuration.md)
 - [Browser provider](operations/controller-browser-plugin.md)
 - [Desktop provider](operations/controller-desktop-plugin.md)
 - [Local system assistant](operations/local-system-assistant.md)
@@ -53,9 +52,10 @@ Forge is Direct-first: investigation does not create durable Work by itself, and
 - [Standalone disaster recovery](operations/standalone-disaster-recovery.md)
 
 ### Maintain
+- [Roadmap](ROADMAP.md)
+- [Release changelog](../CHANGELOG.md)
 - [Release process](operations/releasing.md)
 - [Open-source release hygiene](operations/open-source-release-hygiene.md)
-- [GitHub repository baseline](operations/github-repository.md)
 - [Versioning](versioning.md)
 - [Security policy](../SECURITY.md)
 
@@ -69,4 +69,4 @@ Forge is Direct-first: investigation does not create durable Work by itself, and
 
 ## Authority and history
 
-Current architecture lives in [`architecture/current/`](architecture/current/). The [architecture index](architecture/index.md) and [consolidated history](architecture/history.md) explain superseded designs. Research notes under [`researches/`](researches/) are evidence, not current contracts.
+Current architecture lives only in [`architecture/CURRENT.md`](architecture/CURRENT.md). [`ROADMAP.md`](ROADMAP.md) records current priorities, [`architecture/EVOLUTION.md`](architecture/EVOLUTION.md) records architecture history, and [`architecture/versions/`](architecture/versions/) stores release-family snapshots. Research notes and task records are evidence, not current contracts.