@moretea-labs/forge 1.6.0 → 1.7.1

package/assets/hooks/session-start-context.sh

@@ -397,16 +397,71 @@ current_status_field() {
   ' "$file" | xargs
 }
 
+current_status_stale_after() {
+  local file="$1"
+  local value
+  value="$(current_status_field "$file" "Stale After" 2>/dev/null || true)"
+  if [[ -z "$value" ]]; then
+    value="$(sed -nE 's/^<!--[[:space:]]*stale_after:[[:space:]]*([^[:space:]]+)[[:space:]]*-->$/\1/p' "$file" 2>/dev/null | head -1)"
+  fi
+  printf '%s' "$value"
+}
+
+current_status_updated_epoch() {
+  local value="$1"
+  if date -d "$value" '+%s' >/dev/null 2>&1; then
+    date -d "$value" '+%s'
+    return 0
+  fi
+  date -j -f '%Y-%m-%dT%H:%M:%S%z' "$value" '+%s' 2>/dev/null
+}
+
+# Returns success when the declared freshness contract says the snapshot is
+# expired. A malformed timestamp/duration fails closed once stale_after exists.
+current_status_snapshot_is_stale() {
+  local updated="$1"
+  local stale_after="$2"
+  local amount unit multiplier updated_epoch now_epoch
+  [[ -n "$stale_after" ]] || return 1
+  if [[ ! "$stale_after" =~ ^([0-9]+)([smhd])$ ]]; then
+    return 0
+  fi
+  amount="${BASH_REMATCH[1]}"
+  unit="${BASH_REMATCH[2]}"
+  case "$unit" in
+    s) multiplier=1 ;;
+    m) multiplier=60 ;;
+    h) multiplier=3600 ;;
+    d) multiplier=86400 ;;
+  esac
+  updated_epoch="$(current_status_updated_epoch "$updated" || true)"
+  [[ "$updated_epoch" =~ ^[0-9]+$ ]] || return 0
+  now_epoch="${FORGE_CURRENT_STATUS_NOW_EPOCH:-$(date '+%s')}"
+  [[ "$now_epoch" =~ ^[0-9]+$ ]] || return 0
+  (( now_epoch - updated_epoch >= amount * multiplier ))
+}
+
 current_status_snapshot_context() {
   local current_file="tasks/current.md"
-  local target branch status updated source_commit target_status target_updated
+  local target branch status updated stale_after source_commit target_status target_updated
 
   target="$(workflow_target_branch)"
   branch="$(workflow_current_branch)"
   status="$(current_status_field "$current_file" "Status" 2>/dev/null || true)"
   updated="$(current_status_field "$current_file" "Updated At" 2>/dev/null || true)"
+  stale_after="$(current_status_stale_after "$current_file" 2>/dev/null || true)"
   source_commit="$(current_status_field "$current_file" "Source Commit" 2>/dev/null || true)"
 
+  if current_status_snapshot_is_stale "$updated" "$stale_after"; then
+    cat <<EOF_CONTEXT
+# Stale Current Status Snapshot
+
+- Ignored snapshot: `${current_file}` exceeded its declared freshness contract.
+- Rule: do not use its status, source commit, or focus as current truth; rebuild from active plans, workstreams, handoff, checks, and the target branch.
+EOF_CONTEXT
+    return 0
+  fi
+
   if [[ -z "$status" ]]; then
     if [[ "$branch" != "$target" ]] && git rev-parse --verify --quiet "$target" >/dev/null 2>&1 \
       && git show "${target}:tasks/current.md" >/dev/null 2>&1; then

package/assets/partials/05-workflow.partial.md

@@ -28,7 +28,7 @@ PLAN_LOOP:
   LESSONS_FILE: tasks/lessons.md
   CONTEXT_MAP: .ai/context/context-map.json
   ANNOTATION_GUARD: do not implement until plan Status is "Approved"
-  CONTRACT_GUARD: do not mark done until contract exit criteria pass and review recommends pass
+  CONTRACT_GUARD: do not mark done until contract exit criteria pass; then perform a fresh semantic impact review
   EXECUTION_CONTEXT: contract-level work starts in a linked codex/<slug> worktree when policy enables it; primary worktree warning by default; enforce via .claude/.require-worktree
   CONTRACT_WORKTREE_FINISH: run Forge /review, fill the review artifact from that verdict, then .ai/harness/scripts/contract-worktree.sh finish
   COMMIT_POLICY: explicit commits after green checks; no automatic checkpoint hook

package/assets/partials-agents/02-operating-mode.partial.md

@@ -8,6 +8,8 @@
 - Claude runtime expectation: `{{CLAUDE_POLICY}}`.
 - Codex runtime expectation: `{{CODEX_POLICY}}`.
 - Do not implement until the user explicitly asks to implement.
+- Once the user asks to execute, minimize avoidable human intervention: continue reversible, policy-allowed implementation, verification, cleanup, and delivery autonomously, stopping only at a genuinely user-only identity/legal/financial/strong-confirmation/irreversible boundary.
+- For authenticated browser work, reuse the user's already-running signed-in Google Chrome with attach-preferred, native-auto, Chrome-only, fail-closed routing. Preserve cookies, tokens, sessions, and settings; never silently switch to a managed, isolated, Vivaldi, or otherwise unauthenticated profile unless the task explicitly requests that mode.
 - Stable product truth: `docs/spec.md`.
 - Research reports: `docs/researches/`.
 - Deferred-goal ledger: `tasks/todos.md` (active execution stays in the plan's `## Task Breakdown`).

package/assets/partials-agents/03-orchestration.partial.md

@@ -34,7 +34,7 @@
 ### 6b. Contract Verification
 - Use task contracts in `tasks/contracts/` as completion gates.
 - Use implementation notes in `tasks/notes/` for task-local decisions that should not automatically become memory.
-- Validate exit criteria and the Forge `/review` review recommendation before any done/completed response.
+- Validate direct exit criteria, then use Forge `/review` to reassess intent, downstream impact, and missing state transitions before any done/completed response.
 
 ### 7. Balanced Elegance
 - Redesign hacky non-trivial fixes before shipping.

package/assets/plugin-registry.v1.json

@@ -4,12 +4,12 @@
     {
       "id": "desktop_operator",
       "name": "Forge Desktop Operator",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "description": "Native macOS desktop automation provider for Forge.",
       "repository": "https://github.com/moretea-labs/forge-desktop-operator.git",
-      "ref": "v0.2.1",
+      "ref": "v0.2.3",
       "installer": "forge-plugin-install.mjs",
-      "providerVersion": "0.2.0",
+      "providerVersion": "0.2.3",
       "protocolVersion": "1.0",
       "platforms": [
         "darwin"

package/assets/reference-configs/document-generation.md

@@ -31,7 +31,7 @@ Create these only when the agent has concrete repo evidence or the user asks:
 - Prefer short docs that name sources, owners, and verification commands.
 - Let capability `CLAUDE.md` and `AGENTS.md` carry local contract projections; root docs stay concise.
 - Keep complete workstream TODOs in `tasks/workstreams/<domain>/<capability>/`; contract blocks should link to them instead of becoming task logs.
-- Keep onboarding docs split by reader: agents read active source artifacts first; humans review the Human Review Card, diff, latest trace, and rollback first.
+- Keep onboarding docs split by reader: agents read active source artifacts first; humans review the semantic-impact evidence, diff, latest checks, and recovery options first.
 - Hooks may create `docs/architecture/requests/*.md`; agents own semantic snapshots, embedded Mermaid, and optional `mermaid` HTML output.
 - Archive handled architecture requests with `.ai/harness/scripts/archive-architecture-request.sh`; keep `docs/architecture/requests/` pending-only and preserve handled requests under `docs/architecture/requests/archive/YYYY/`.
 - When both Mermaid and HTML exist, keep the Mermaid in Markdown as the semantic source and make the HTML link back to that Markdown source.

package/assets/reference-configs/harness-overview.md

@@ -92,7 +92,7 @@ Required v1 fields:
 - `commands`, `guards`, `handoffs`, `files_changed`, and `allowed_paths_check`
 - `external_acceptance`, `failure_class`, and `next_step`
 
-`scripts/check-task-workflow.sh --strict` validates the latest trace shape when a non-empty latest checks file exists. `scripts/harness-trace-grade.sh --run <trace> --strict` applies the local graders used for workflow regression checks: active plan resolves, contract profile is valid, Human Review Card passes, command evidence exists, and changed files stay inside allowed paths.
+`scripts/check-task-workflow.sh --strict` validates the latest trace shape when a non-empty latest checks file exists. Behavioral evidence comes from the selected checks and fresh controller review, not a score of plan or review metadata.
 
 ## Capability Context
 

package/assets/reference-configs/sprint-contracts.md

@@ -78,12 +78,12 @@ Existing contracts without this block remain valid. `.ai/harness/scripts/verify-
 
 ## Review Coupling
 
-- A contract is not truly done until the matching review file records a passing recommendation.
-- `tasks/reviews/<plan-stem>.review.md` should be filled from Forge `/review` after verification and cite the contract, implementation notes, checks file, run snapshot, `## External Acceptance Advice`, and any manual observations.
+- After direct verification, use Forge `/review` for a fresh semantic impact review: user intent, affected domains, downstream consumers, missing state transitions, scenario evidence, and residual risks. The review is controller context, not a parser-owned completion gate.
+- `tasks/reviews/<plan-stem>.review.md` may cite the contract, implementation notes, checks file, run snapshot, and manual observations when they clarify the impact review.
 - `tasks/notes/<plan-stem>.notes.md` captures task-local decisions and should be archived or promoted deliberately, not left as hidden long-term memory.
 
 ## Worktree Lifecycle
 
 - When `.ai/harness/policy.json` has `worktree_strategy.auto_for_contract_tasks: true`, `.ai/harness/scripts/plan-to-todo.sh --plan <approved-plan>` starts a linked `codex/<slug>` worktree instead of mutating the primary tree.
 - Execute the sprint in that linked worktree. The primary worktree remains a merge target and must stay clean before merge-back.
-- After implementation, run Forge `/review` so the review file recommends pass, record passing `## External Acceptance Advice` from the peer reviewer or a concrete manual override, then run `.ai/harness/scripts/contract-worktree.sh finish`. The finish command gates on external acceptance before `verify-sprint.sh`, commits the branch, and fast-forwards the target branch only when the target worktree is clean.
+- After implementation, run Forge `/review` to reassess behavior beyond the changed files, then run `.ai/harness/scripts/contract-worktree.sh finish`. Completion uses direct contract checks and declared scope; the finish command commits the branch and fast-forwards the target only when that target worktree is clean.

package/assets/skill-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.6.0",
-  "templateVersion": "1.6.0",
+  "version": "1.7.1",
+  "templateVersion": "1.7.1",
   "skillName": "forge",
   "contractId": "tasks-first-harness-v1",
   "compatibility": {

package/assets/templates/contract.template.md

@@ -27,7 +27,7 @@ Describe the exact outcome this task must deliver.
 - Checks file: `.ai/harness/checks/latest.json`
 - Run snapshots: `.ai/harness/runs/`
 - Scope gate: edit only paths listed under `allowed_paths`; update this contract before widening scope.
-- Completion gate: `scripts/verify-sprint.sh` must see this contract pass, the review recommend pass, and `## External Acceptance Advice` pass or record a manual override.
+- Completion evidence: `scripts/verify-sprint.sh` reports this contract's direct checks and declared scope. Then perform a fresh semantic impact review.
 
 ## Allowed Paths
 
@@ -84,12 +84,7 @@ exit_criteria:
   tests_pass:
     - path: tests/unit/{{TASK_SLUG}}.test.ts
   commands_succeed:
-    - bun run typecheck
-  qa_scores:
-    - dimension: functionality
-      min: 7
-  manual_checks:
-    - "Evaluator review file recommends pass"
+    - bun run check:type
 ```
 
 ## Acceptance Notes (Human Review)

package/assets/templates/helpers/capture-plan.sh

@@ -302,8 +302,8 @@ See captured planning output.
 
 - **State/progress path**: \`${plan_file}\` task breakdown, \`tasks/todos.md\` deferred-goal ledger, \`tasks/contracts/${artifact_stem}.contract.md\`, \`tasks/reviews/${artifact_stem}.review.md\`, and \`tasks/notes/${artifact_stem}.notes.md\`
 - **Verification evidence**: \`.ai/harness/checks/latest.json\`, \`.ai/harness/runs/\`, and the commands named in the captured planning output
-- **Evaluator rubric**: \`tasks/reviews/${artifact_stem}.review.md\` must record a passing Forge /review style recommendation
-- **Stop condition**: all task breakdown items are complete, sprint verification passes, and the review recommends pass
+- **Impact review**: after direct checks, reassess user intent, affected domains, downstream consumers, state transitions, and residual risks
+- **Stop condition**: all task breakdown items are complete and sprint verification reports direct checks plus declared scope passing
 - **Rollback surface**: before execution remove \`${plan_file}\`; after execution revert branch \`codex/${slug}\` or the generated task artifacts
 
 ## Captured Planning Output

package/assets/templates/helpers/check-architecture-sync.sh

@@ -212,6 +212,23 @@ if ! bash scripts/architecture-queue.sh reindex --check >/dev/null; then
   exit 1
 fi
 
+if [[ -f "docs/architecture/current/README.md" ]]; then
+  if [[ ! -f "docs/architecture/CURRENT.md" ]]; then
+    echo "[ArchitectureSync] architecture baseline failed: missing required file docs/architecture/CURRENT.md" >&2
+    exit 1
+  fi
+
+  if ! grep -Fq "Runtime Authority" "docs/architecture/CURRENT.md"; then
+    echo "[ArchitectureSync] architecture baseline failed: docs/architecture/CURRENT.md must contain: Runtime Authority" >&2
+    exit 1
+  fi
+
+  if ! grep -Fq "Not Runtime Authority" "docs/architecture/current/README.md"; then
+    echo "[ArchitectureSync] architecture baseline failed: docs/architecture/current/README.md must contain: Not Runtime Authority" >&2
+    exit 1
+  fi
+fi
+
 if [[ "$mode" == "off" ]]; then
   case "$format" in
     json) printf '{"mode":"off","changed_capabilities":0,"blocking":0}\n' ;;

package/assets/templates/helpers/check-task-workflow.sh

@@ -161,7 +161,7 @@ plan_evidence_contract_error() {
   fi
 
   local label line value
-  for label in "State/progress path" "Verification evidence" "Evaluator rubric" "Stop condition" "Rollback surface"; do
+  for label in "State/progress path" "Verification evidence" "Impact review|Evaluator rubric" "Stop condition" "Rollback surface"; do
     line="$(printf '%s\n' "$section" | grep -Ei "^[[:space:]]*-[[:space:]]*(\\*\\*)?${label}(\\*\\*)?[[:space:]]*:" | head -1 || true)"
     if [[ -z "$line" ]]; then
       echo "missing field: ${label}"
@@ -189,7 +189,7 @@ check_plan_template_evidence_contract() {
     return
   }
 
-  for label in "State/progress path" "Verification evidence" "Evaluator rubric" "Stop condition" "Rollback surface"; do
+  for label in "State/progress path" "Verification evidence" "Impact review" "Stop condition" "Rollback surface"; do
     if ! grep -Eiq "^[[:space:]]*-[[:space:]]*(\\*\\*)?${label}(\\*\\*)?[[:space:]]*:" "$file"; then
       report_issue "Plan template Evidence Contract is missing field '${label}': $file"
     fi
@@ -668,11 +668,11 @@ check_helper_runtime_files() {
       new-spec.sh new-sprint.sh new-plan.sh capture-plan.sh plan-to-todo.sh
       contract-run.ts contract-worktree.sh ship-worktrees.sh archive-workflow.sh
       refresh-current-status.sh prepare-handoff.sh 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
+      verify-sprint.sh sprint-backlog.sh check-task-sync.sh check-deploy-sql-order.sh
       check-architecture-sync.sh check-agent-tooling.sh check-context-files.sh
       check-brain-manifest.sh sync-brain-docs.sh check-skill-version.ts
       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
+      switch-plan.sh workflow-contract.ts
       inspect-project-state.ts migrate-workflow-docs.ts migrate-project-template.sh
       capability-resolver.ts architecture-event.ts capability-config.ts architecture-queue.sh
       archive-architecture-request.sh context-contract-sync.sh workstream-sync.sh

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

@@ -456,8 +456,7 @@ finish_worktree() {
     exit 1
   fi
 
-  local current_branch slug active_plan contract_file review_file target_worktree artifact_stem
-  local external_status external_state external_reviewer external_source external_message
+  local current_branch slug active_plan contract_file target_worktree artifact_stem
   current_branch="$(git branch --show-current)"
   [[ -n "$current_branch" ]] || { echo "contract-worktree: detached HEAD is not supported" >&2; exit 1; }
   [[ "$current_branch" != "$target_branch" ]] || { echo "contract-worktree: already on target branch $target_branch" >&2; exit 1; }
@@ -470,7 +469,6 @@ finish_worktree() {
     active_plan="$(get_active_plan || true)"
     if [[ -n "$active_plan" ]]; then
       contract_file="$(workflow_active_contract || true)"
-      review_file="$(workflow_active_review || true)"
     fi
   fi
 
@@ -483,27 +481,9 @@ finish_worktree() {
       contract_file="tasks/contracts/${artifact_stem}.contract.md"
     fi
   fi
-  if [[ -n "${active_plan:-}" && -z "${review_file:-}" ]]; then
-    artifact_stem="${artifact_stem:-$(derive_artifact_stem_from_plan "$active_plan")}"
-    if [[ -f "tasks/reviews/${artifact_stem}.review.md" ]] || [[ ! -f "tasks/reviews/${slug}.review.md" ]]; then
-      review_file="tasks/reviews/${artifact_stem}.review.md"
-    fi
-  fi
   contract_file="${contract_file:-tasks/contracts/${slug}.contract.md}"
-  review_file="${review_file:-tasks/reviews/${slug}.review.md}"
 
   [[ -n "$contract_file" && -f "$contract_file" ]] || { echo "contract-worktree: no active sprint contract found" >&2; exit 1; }
-  [[ -n "$review_file" && -f "$review_file" ]] || { echo "contract-worktree: no active sprint review found" >&2; exit 1; }
-
-  if declare -F workflow_external_acceptance_status >/dev/null 2>&1; then
-    external_status="$(workflow_external_acceptance_status "$review_file")"
-    IFS=$'\t' read -r external_state external_reviewer external_source external_message <<< "$external_status"
-    if [[ "$external_state" != "pass" && "$external_state" != "manual_override" ]]; then
-      echo "contract-worktree: external acceptance gate failed: ${external_message:-missing external acceptance}" >&2
-      echo "contract-worktree: record ## External Acceptance Advice in $review_file via $(workflow_external_acceptance_expected_source) before finish" >&2
-      exit 1
-    fi
-  fi
 
   check_architecture_freshness "$target_branch"
   bash "scripts/verify-sprint.sh"

package/assets/templates/helpers/ensure-task-workflow.sh

@@ -348,7 +348,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**:
 
@@ -391,7 +391,7 @@ Describe the exact outcome this task must deliver.
 - Checks file: `.ai/harness/checks/latest.json`
 - Run snapshots: `.ai/harness/runs/`
 - Scope gate: edit only paths listed under `allowed_paths`; update this contract before widening scope.
-- Completion gate: `scripts/verify-sprint.sh` must see this contract pass, the review recommend pass, and `## External Acceptance Advice` pass or record a manual override.
+- Completion evidence: `scripts/verify-sprint.sh` reports this contract's direct checks and declared scope. Then perform a fresh semantic impact review.
 
 ## Allowed Paths
 
@@ -444,7 +444,7 @@ exit_criteria:
   tests_pass:
     - path: tests/unit/{{TASK_SLUG}}.test.ts
   commands_succeed:
-    - bun run typecheck
+    - bun run check:type
   files_contain:
     - path: src/modules/{{TASK_SLUG}}/index.ts
       pattern: "export"
@@ -473,48 +473,23 @@ CONTRACT_TEMPLATE_EOF
 > **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:
 
 ## Verification Evidence
 
-- Forge /review run:
+- Focused/full checks:
 - Commands run:
 - Manual checks:
 - Supporting artifacts:
 
-## External Acceptance Advice
-
-> **External Acceptance**: unavailable
-> **External Reviewer**:
-> **External Source**:
-> **External Started**:
-> **External Completed**:
-
-- P1 blockers:
-- P2 advisories:
-- Acceptance checklist:
-
-## Scorecard
-
-| Dimension | Score | Notes |
-|-----------|-------|-------|
-| Functionality | 0/10 | |
-| Product depth | 0/10 | |
-| Design quality | 0/10 | |
-| Code quality | 0/10 | |
-
 ## Failing Items
 
 - ...

package/assets/templates/helpers/inspect-project-state.ts

@@ -270,11 +270,13 @@ function renderText(result: InspectionResult): string {
   return lines.join("\n");
 }
 
-const { repo, format } = parseArgs(process.argv.slice(2));
-const result = inspectRepo(repo);
+if (import.meta.main) {
+  const { repo, format } = parseArgs(process.argv.slice(2));
+  const result = inspectRepo(repo);
 
-if (format === "text") {
-  console.log(renderText(result));
-} else {
-  console.log(JSON.stringify(result, null, 2));
+  if (format === "text") {
+    console.log(renderText(result));
+  } else {
+    console.log(JSON.stringify(result, null, 2));
+  }
 }

package/assets/templates/helpers/migrate-project-template.sh

@@ -1,54 +1,31 @@
 #!/bin/bash
-# Delegate workflow migrations to the canonical upstream forge.
-#
-# Generated projects keep installed workflow runtime state under .ai/. The
-# template source lives in AGENTIC_DEV_ROOT, AGENTIC_DEV_SKILL_ROOT, or
-# ~/Projects/forge. Retired legacy install paths are not
-# searched.
+# Run the canonical Forge adoption path without guessing a developer checkout.
 
 set -euo pipefail
 
-resolve_agentic_dev_root() {
-  if [[ -n "${AGENTIC_DEV_ROOT:-}" ]]; then
-    printf '%s\n' "$AGENTIC_DEV_ROOT"
-    return 0
-  fi
-
-  if [[ -n "${AGENTIC_DEV_SKILL_ROOT:-}" ]]; then
-    printf '%s\n' "$AGENTIC_DEV_SKILL_ROOT"
-    return 0
-  fi
-
-  if [[ -n "${HOME:-}" ]]; then
-    local roots=(
-      "$HOME/Projects/forge"
-      "$HOME/.codex/skills/forge"
-      "$HOME/.claude/skills/forge"
-      "$HOME/.agents/skills/forge"
-    )
-
-    local root
-    for root in "${roots[@]}"; do
-      if [[ -d "$root" ]]; then
-        printf '%s\n' "$root"
-        return 0
-      fi
-    done
-
-    printf '%s\n' "${roots[0]}"
-    return 0
-  fi
-
-  printf '%s\n' ".forge/skills/forge"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SELF_SOURCE_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SOURCE_ROOT="${FORGE_SOURCE_ROOT:-${AGENTIC_DEV_ROOT:-${AGENTIC_DEV_SKILL_ROOT:-}}}"
+
+run_source_root() {
+  local root="$1"
+  shift
+  [[ -f "$root/src/cli/index.ts" ]] || return 1
+  command -v bun >/dev/null 2>&1 || {
+    echo "[migrate] bun is required to run Forge from source: $root" >&2
+    exit 1
+  }
+  exec bun "$root/src/cli/index.ts" adopt "$@" --no-codegraph --no-verify
 }
 
-UPSTREAM_ROOT="$(resolve_agentic_dev_root)"
-UPSTREAM_SCRIPT="$UPSTREAM_ROOT/scripts/migrate-project-template.sh"
+run_source_root "$SELF_SOURCE_ROOT" "$@"
+if [[ -n "$SOURCE_ROOT" ]]; then
+  run_source_root "$SOURCE_ROOT" "$@"
+fi
 
-if [[ ! -f "$UPSTREAM_SCRIPT" ]]; then
-  echo "[migrate] Upstream forge migration script not found: $UPSTREAM_SCRIPT" >&2
-  echo "[migrate] Set AGENTIC_DEV_ROOT or AGENTIC_DEV_SKILL_ROOT to the skill root." >&2
-  exit 1
+if command -v forge >/dev/null 2>&1; then
+  exec forge adopt "$@" --no-codegraph --no-verify
 fi
 
-exec bash "$UPSTREAM_SCRIPT" "$@"
+echo "[migrate] Missing Forge CLI; set FORGE_SOURCE_ROOT to a Forge source checkout." >&2
+exit 1

package/assets/templates/helpers/migrate-workflow-docs.ts

@@ -403,11 +403,13 @@ function renderText(summary: MigrationSummary): string {
   return lines.join("\n");
 }
 
-const { repo, mode, format } = parseArgs(process.argv.slice(2));
-const summary = migrate(repo, mode);
-
-if (format === "json") {
-  console.log(JSON.stringify(summary, null, 2));
-} else {
-  console.log(renderText(summary));
+if (import.meta.main) {
+  const { repo, mode, format } = parseArgs(process.argv.slice(2));
+  const summary = migrate(repo, mode);
+
+  if (format === "json") {
+    console.log(JSON.stringify(summary, null, 2));
+  } else {
+    console.log(renderText(summary));
+  }
 }

package/assets/templates/helpers/new-plan.sh

@@ -141,7 +141,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/helpers/plan-to-todo.sh

@@ -63,7 +63,7 @@ plan_evidence_contract_error() {
   fi
 
   local label line value
-  for label in "State/progress path" "Verification evidence" "Evaluator rubric" "Stop condition" "Rollback surface"; do
+  for label in "State/progress path" "Verification evidence" "Impact review|Evaluator rubric" "Stop condition" "Rollback surface"; do
     line="$(printf '%s\n' "$section" | grep -Ei "^[[:space:]]*-[[:space:]]*(\\*\\*)?${label}(\\*\\*)?[[:space:]]*:" | head -1 || true)"
     if [[ -z "$line" ]]; then
       echo "missing field: ${label}"
@@ -323,7 +323,7 @@ Describe the exact outcome this task must deliver.
 - Checks file: `.ai/harness/checks/latest.json`
 - Run snapshots: `.ai/harness/runs/`
 - Scope gate: edit only paths listed under `allowed_paths`; update this contract before widening scope.
-- Completion gate: `scripts/verify-sprint.sh` must see this contract pass, the review recommend pass, and `## External Acceptance Advice` pass or record a manual override.
+- Completion evidence: `scripts/verify-sprint.sh` reports this contract's direct checks and declared scope. Then perform a fresh semantic impact review.
 
 ## Allowed Paths
 
@@ -377,7 +377,7 @@ exit_criteria:
   tests_pass:
     - path: tests/unit/{{TASK_SLUG}}.test.ts
   commands_succeed:
-    - bun run typecheck
+    - bun run check:type
   files_contain:
     - path: src/modules/{{TASK_SLUG}}/index.ts
       pattern: "export"
@@ -691,19 +691,15 @@ else
 > **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
 
@@ -713,26 +709,14 @@ else
 
 ## Verification Evidence
 
-- Forge /review 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
 
 - ...
 
@@ -740,15 +724,6 @@ else
 
 - ...
 
-## Scorecard
-
-| Dimension | Score | Notes |
-|-----------|-------|-------|
-| Functionality | 0/10 | |
-| Product depth | 0/10 | |
-| Design quality | 0/10 | |
-| Code quality | 0/10 | |
-
 ## Failing Items
 
 - ...