@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -1,124 +1,34 @@
 # Harness Overview
 
-This repo uses a shared long-running harness. The durable workflow lives in repo-local artifacts, not in chat memory.
+Forge uses ChatGPT (or another explicit semantic Controller) for interpretation and decisions, while Forge owns deterministic execution, durable Runtime authority, scoped authorization/resource fencing, evidence, verification, recovery, and optional continuation.
 
-## Adoption Model
+## Current state boundary
 
-Use this file as the first onboarding map after `forge adopt` installs
-or refreshes a repo. The harness gives agents three durable surfaces:
+- Repository-authored/declarative surfaces: source, tests, `docs/spec.md`, `docs/researches/`, `tasks/todos.md`, `tasks/lessons.md`, intentional human-maintained plans/docs, and root `forge.config.json`.
+- Controller Home: Requirement/Plan/Work/ControllerRound, Schedule/occurrence, Process/Job, leases/resource claims, authorization requests/grants, verification receipts, mutable Plugin configuration, Runtime/session bindings, operational evidence, recovery state, and retention metadata.
+- Provider/cache/temp data: Controller-owned provider/cache roots with explicit retention, or OS temp for disposable scratch.
 
-- **Shared standards**: `docs/spec.md`, `docs/reference-configs/`, root
-  `AGENTS.md`, and root `CLAUDE.md` explain stable product intent, coding
-  rules, and local workflow boundaries.
-- **Task contracts**: `plans/`, `tasks/contracts/`, `tasks/reviews/`, and
-  `.ai/harness/checks/` turn a request into scoped implementation work with
-  evidence-backed completion.
-- **Session cache**: `.ai/harness/session/`, `tasks/current.md`, and
-  `.ai/harness/events.jsonl` let a new agent session resume from repo state
-  without treating chat history as authority.
+A Markdown or JSON file is not repository source merely because a human can read it. Ownership, authority, lifecycle, and retention decide placement.
 
-The install is not an app scaffold or an agent gateway. It adds a reviewable
-workflow contract around an existing repo, then leaves product code ownership
-with the project.
+## Workflow
 
-## Roles
+1. **Understand**: use current raw source and bounded context evidence.
+2. **Design**: for material/high-risk changes, close the Engineering Design contract across identity/authority, authorization, resources, lifecycle, persistence, replay, evidence, recovery, topology, capacity, security, portability, migration, release, and performance.
+3. **Plan only when useful**: bounded understood work may remain direct; durable Plan/Work is for real decomposition, continuity, isolation, scheduling, recovery, or external effects.
+4. **Execute coherently**: one owner, one mutable authority, explicit resource claims, no incident-specific parallel lifecycle.
+5. **Review and verify**: implementation review is tied to exact source/workspace/check evidence and the same design/acceptance contract.
+6. **Terminalize**: release leases/worktrees/temp state, retain only policy-required evidence, and let bounded GC reclaim terminal operational data.
 
-- **Planner** updates `docs/spec.md`, researches constraints, and writes or approves `plans/plan-*.md`.
-- **Generator** implements only against the active sprint contract and the plan's `## Task Breakdown`, leaving `tasks/todos.md` as a deferred-goal ledger, and records task-local implementation judgments in `tasks/notes/<plan-stem>.notes.md`.
-- **Evaluator** runs Forge `/review`, then writes `tasks/reviews/<plan-stem>.review.md` using fresh evidence from `.ai/harness/checks/latest.json` and `.ai/harness/runs/*.json`.
+## Omission and drift control
 
-## State Flow
+Prompt instructions are advisory. Correctness comes from executable gates:
 
-1. `docs/spec.md` captures stable product intent.
-2. `plans/plan-*.md` captures a concrete execution approach.
-3. `tasks/contracts/<plan-stem>.contract.md` defines done for the active sprint.
-4. `tasks/current.md` is a tracked mainline status snapshot derived from workflow artifacts; it is not a live lock, kanban board, or implementation gate.
-5. `tasks/todos.md` is the deferred-goal ledger; the plan's `## Task Breakdown` and active contract carry sprint execution.
-6. `tasks/notes/<plan-stem>.notes.md` records design decisions, deviations, tradeoffs, open questions, and promotion candidates for this sprint only.
-7. `tasks/reviews/<plan-stem>.review.md` records evaluator judgment.
-8. `.ai/harness/policy.json` is the machine-readable workflow contract.
-9. `information_lifecycle` inside `.ai/harness/policy.json` separates notes, raw evidence, reusable assets, advisory memory, and external knowledge.
-10. `agentic_development` inside `.ai/harness/policy.json` captures product, engineering, design, bug-hunt, and review routing.
-11. `external_tooling` inside `.ai/harness/policy.json` captures host install/update defaults for gstack, Waza, gbrain, and required CodeGraph readiness.
-12. `.ai/context/capabilities.json` declares capability prefixes, contract files, architecture modules, and workstream directories.
-13. `.ai/context/context-map.json` indexes stable root context and discoverable capability context derived from the registry.
-14. `documentation` inside `.ai/harness/policy.json` keeps generated docs minimal and moves optional docs to agent-created, evidence-backed output.
-15. `lsp_profiles` inside policy and context-map files select tooling hints per capability.
-16. `worktree_strategy` inside policy tells agents when to isolate contract-level work in `codex/<slug>` worktrees, start execution through `.ai/harness/scripts/contract-worktree.sh start --plan <plan>`, and finish with Forge `/review` plus `.ai/harness/scripts/contract-worktree.sh finish`.
-17. `.ai/harness/session/continuation.md` preserves resumable state across sessions.
-18. `.ai/harness/events.jsonl` and `.ai/harness/runs/*.json` retain lightweight execution traces.
+- Context Closure makes material evidence gaps visible before design.
+- Engineering Design receipts require cross-cutting decisions for high-risk work.
+- Plan supersession must reconcile unresolved predecessor obligations as KEEP/CHANGE/DEFER/DROP.
+- Implementation review and verification bind to exact source/workspace/check identity.
+- Repository hygiene prevents modern producers from recreating repo-local Runtime state.
 
-## Session Boundaries
+## Legacy compatibility
 
-- Exploration and planning are allowed before a contract exists.
-- Before implementation, the plan and contract should both expose a concrete workflow inventory so the agent does not rediscover or guess active artifacts.
-- Implementation should prefer `docs/spec.md`, an approved plan, and an active sprint contract.
-- Claiming completion should include contract verification evidence, a run snapshot, implementation notes, and a passing Forge `/review` artifact.
-- Stopping a session should refresh `.ai/harness/session/continuation.md` for easier resume; while pending planning orchestration is open, Stop may block once to force a plan completeness self-review before execution.
-- Refresh `tasks/current.md` with `.ai/harness/scripts/refresh-current-status.sh --write --reason <reason>` only at explicit lifecycle boundaries or as a deliberate maintainer action; ordinary hooks should not dirty tracked files.
-- In non-target worktrees, read the target branch snapshot with `git show <target>:tasks/current.md` and verify stale or surprising state against the source artifacts before acting.
-- Use `docs/reference-configs/agentic-development-flow.md` for skill routing and `docs/reference-configs/external-tooling.md` for install/update commands.
-- Use `docs/reference-configs/global-working-rules.md` as the user-level Claude/Codex rule template; keep repo-local workflow contracts in repo files.
-- Externalized reference docs are indexed by `.ai/harness/brain-manifest.json` and checked by `.ai/harness/scripts/check-brain-manifest.sh`. Valuable repo docs can opt into default-brain mirroring with `sync.direction=repo-to-brain`; `post-edit-guard.sh` then calls `.ai/harness/scripts/sync-brain-docs.sh --changed <path>` for that specific file.
-- Contract-level execution should run in an isolated `codex/<task-slug>` worktree. Merge back only after the contract is fulfilled, `tasks/reviews/<plan-stem>.review.md` recommends pass, and the target worktree is clean.
-- Architecture-sensitive work also runs `scripts/check-architecture-sync.sh`: the check keeps the request index derived from `docs/architecture/requests/` and, when policy is strict, blocks finish if the current diff touches a capability with a pending architecture request at or above `architecture.gate_min_severity`.
-- Migration cleans legacy root `scripts/<forge-helper>` files only when content is identifiable as generated forge runtime; ambiguous app-owned root scripts are reported and preserved.
-
-## Documentation Profile
-
-- Default profile: `minimal-agentic`.
-- Required docs: `docs/spec.md` and `docs/architecture/index.md`.
-- Optional docs such as `docs/brief.md`, `docs/tech-stack.md`, `docs/decisions.md`, `docs/architecture.md`, and `docs/packages.md` are created only when the agent has concrete repo evidence or the user asks.
-- Root `specs/` is a legacy scaffold surface; use `docs/spec.md`, `interfaces/`, and tests instead.
-- Use `docs/reference-configs/document-generation.md` for the creation rules.
-
-## Information Lifecycle
-
-- Notes: `tasks/notes/<plan-stem>.notes.md` is task-local and auditable. It should not be treated as durable knowledge by default.
-- Current status: `tasks/current.md` is a tracked derived snapshot for orientation only. It must be regenerated from source artifacts and must not contain hand-written kanban/checklist state.
-- Evidence: `.ai/harness/checks/latest.json` is the current gate, while `.ai/harness/runs/*.json` keeps immutable verification snapshots for later audit.
-- Memory: `docs/researches/`, `tasks/lessons.md`, and gbrain are advisory. Current repo state and evidence override summaries.
-- External knowledge: `brain/<project>/*` stores long-form explanations, runbooks, decisions, and patterns. Hooks may write only explicitly opted-in `repo-to-brain` manifest entries; checks must not require gbrain or MCP.
-- Assets: policies, hooks, scripts, templates, and reference configs only change when a pattern has evidence across tasks or fixtures.
-
-## Trace Evidence
-
-`scripts/verify-sprint.sh` writes `.ai/harness/checks/latest.json` and an immutable `.ai/harness/runs/*.json` snapshot using `schema: forge-run-trace.v1`. The trace is local evidence for workflow grading, not a cloud tracing dependency.
-
-Required v1 fields:
-
-- `run_id`, `generated_at`, `status`, `exit_code`, and `source`
-- `task_profile`, `active_plan`, `contract`, `review`, `worktree`, and `branch`
-- `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. Behavioral evidence comes from the selected checks and fresh controller review, not a score of plan or review metadata.
-
-## Capability Context
-
-- Do not infer agent context boundaries from physical layout globs such as `apps/*`, `packages/*`, or `services/*`.
-- Declare capabilities in `.ai/context/capabilities.json`; each capability owns prefixes, paired contract files, an architecture module, a workstream directory, and local verification hints.
-- Add selected capabilities with `forge-capability` or `bun .ai/harness/scripts/capability-config.ts add --prefix <path>` when the harness already exists and a full init/migrate/upgrade pass would be too broad.
-- Resolve edited paths through `.ai/harness/scripts/capability-resolver.ts match --path <path>`; longest prefix wins and equal-length ambiguity fails.
-- Treat `.ai/context/agent-context-blocks.txt`, `FORGE_CONTEXT_BLOCKS`, and existing nested `CLAUDE.md`/`AGENTS.md` files as migration inputs or compatibility fallbacks only.
-- Selected capabilities receive paired `CLAUDE.md` and `AGENTS.md` files so Claude Code and Codex share the same local contract.
-- Use `forge capability-context status|request|sync` to keep paired local context files aligned with the registry. The command writes only the controlled `CAPABILITY CONTEXT` block and preserves hand-authored content plus the separate architecture contract block.
-- `.ai/context/capability-source-map.json` is the optional human-edited source-map manifest for capability positioning and source pointers. Missing entries fall back to registry/architecture/workstream metadata; `--auto-fill-positioning` writes deterministic draft entries explicitly, not from hooks.
-- `.ai/harness/capability-context/` is ignored runtime queue state. Post-edit hooks may enqueue requests, and `SessionStart` only reminds the current agent to run `forge capability-context sync --pending --apply`.
-- `SessionStart` also summarizes pending architecture request cards so a resumed agent can see drift debt before claiming finish.
-
-## Initializer and Runtime Model
-
-Maintainer-facing detail on how the initializer and runtime defaults are wired.
-
-- Question flow uses **12 grouped decision points** with harness defaults inferred first.
-- Plan menu is tiered: **Core Plans (A-F)** first, **Custom Presets (G-K)** only when needed.
-- Skill routing is inspection-first: `scripts/inspect-project-state.ts`, `scripts/migrate-workflow-docs.ts`, `assets/workflow-contract.v1.json`.
-- Runtime mode is configurable with template vars: `{{RUNTIME_MODE}}`, `{{RUNTIME_PROFILE}}`, `{{RECOVERY_PROFILE}}`, `{{STATE_PROFILE}}`.
-- Question-pack source of truth: `assets/initializer-question-pack.v4.json`.
-- Generated repos default to the repo-local harness flow: `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`.
-- Generated and self-hosted repos install `.ai/harness/workflow-contract.json` and `.ai/harness/policy.json`.
-- Generated and migrated repos route primarily through Forge modes; gstack, Waza, gbrain, and Mermaid are optional host enhancements only.
-- `forge install` bootstraps Forge-owned CLI/runtime and global Codex/Claude hook adapters. Third-party Waza/Mermaid/cross-review skills require explicit `--with-external-skills`; host CodeGraph MCP configuration is optional because Forge structural retrieval uses its bundled backend. `forge setup open/next/close` is the preferred guided first-run workflow.
-- Other external tooling stays advisory-only: `bash scripts/check-agent-tooling.sh --host both --check-updates`; Waza update checks compare upstream `tw93/Waza` `SKILL.md` hashes without running `npx skills check`; no automatic gstack, gbrain MCP, CodeGraph daemon, or provider setup.
-- Manual distillation stays repo-local: repeated corrections -> `tasks/lessons.md`; deep findings and hidden contracts -> topic-scoped `docs/researches/*.md`; sprint verification evidence -> `tasks/reviews/*.review.md`; durable capability progress -> `tasks/workstreams/`; release history -> `docs/CHANGELOG.md`.
+Older `.ai/harness/**`, `tasks/current.md`, `tasks/contracts/`, `tasks/reviews/`, `tasks/notes/`, `tasks/workstreams/`, repo-local Plugin config, and repo-local cache/session surfaces are migration inputs only when a legacy project still contains them. New projects and modern `forge.config.json` projects must not create or mirror-write them. Git history remains the source-history archive; Controller Home owns mutable Runtime history according to retention policy.

package/assets/reference-configs/hook-operations.md

@@ -7,7 +7,7 @@
 Start with the shortest truth path:
 
 1. `~/.claude/settings.json` and `~/.codex/hooks.json` wire host events into `forge-hook` (bash-shim installs use `bash ~/.forge/hook-shim.sh <hook>.sh`), with `forge hook` as the compatibility fallback.
-2. The dispatcher checks whether the current repo is opted in through `.ai/harness/workflow-contract.json` (and, for the bash shim, that its primary root is trusted in `~/.forge/trusted-repos`).
+2. The dispatcher checks whether the current repo is opted in through `forge.config.json` (legacy `.ai/harness/workflow-contract.json` remains migration-only) (and, for the bash shim, that its primary root is trusted in `~/.forge/trusted-repos`).
 3. The route registry selects the ordered hook scripts for that event and route.
 4. Hook scripts resolve **central-first**: env `FORGE_HOOK_SOURCE` (`repo` | `central` | absolute dir) → repo policy pin `"hook_source": "repo"` in `.ai/harness/policy.json` → the central copy → vendored `<repo>/.ai/hooks` fallback. The central copy is `~/.forge/hooks/` (installed by `scripts/forge.sh install`, stamped with `.version`) on the bash chain, and the packaged `assets/hooks/` inside the globally installed CLI on the `forge-hook` chain.
 

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

@@ -74,13 +74,13 @@ Existing contracts without this block remain valid. `.ai/harness/scripts/verify-
 - `Active`: approved for implementation
 - `Blocked`: waiting on a missing dependency or decision
 - `Verified`: all machine checks passed; awaiting or holding review
-- `Archived`: sprint is complete or superseded
+- `Closed`: sprint is complete or superseded; terminal repo-local lifecycle artifacts are removed after exact final evidence is committed
 
 ## Review Coupling
 
 - 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.
+- `tasks/notes/<plan-stem>.notes.md` captures task-local decisions. Promote durable truth to canonical docs/source before closeout; terminal task-local notes are then deleted with their plan lifecycle artifacts after exact final evidence is committed.
 
 ## Worktree Lifecycle
 

package/assets/skill-version.json

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

package/assets/templates/helpers/architecture-event.ts

@@ -367,8 +367,8 @@ function renderRequiredFollowUp(event: ArchitectureEvent): string {
     "- When a visual explains the boundary better than prose, add or update a Mermaid fenced block in the relevant architecture module or snapshot Markdown first; that Markdown is the semantic source for LLM readers.",
     "- When a human-readable rendering is useful, generate a matching `$mermaid` architecture HTML file under `docs/architecture/diagrams/` and link it back to the Markdown semantic source.",
     "- Treat `mermaid` as an external installed skill dependency at `~/.codex/skills/mermaid`; do not copy, vendor, or inline its templates into this repo.",
-    `- If this starts or advances durable execution, run \`scripts/workstream-sync.sh ensure --block "${functionalBlock}" --request "${requestFile}"\`.`,
-    "- After the snapshot or diagram is produced, run `scripts/context-contract-sync.sh sync-latest` so the local architecture contract block links to the latest artifacts.",
+    "- Durable Requirement/Plan/Work progress belongs to Forge Controller Home; do not create repo-local workstream/session projections for this architecture event.",
+    "- After the snapshot or diagram is produced, run `scripts/context-contract-sync.sh sync-latest` so the local architecture contract block links only to authored architecture artifacts.",
   ].join("\n");
 }
 
@@ -407,7 +407,6 @@ function renderRequestCard(event: ArchitectureEvent, events: ArchitectureEvent[]
     `> **Architecture Domain**: \`${event.architecture_domain}\``,
     `> **Architecture Capability**: \`${event.architecture_capability}\``,
     `> **Architecture Module**: \`${event.architecture_module}\``,
-    `> **Workstream Directory**: \`${event.workstream_dir}\``,
     `> **Contract Files**: \`${event.contract_agents || "none"}\`, \`${event.contract_claude || "none"}\``,
     `> **Contract Sync Required**: ${Boolean(event.contract_sync_required)}`,
     `> **Spawn Recommended**: ${events.some((entry) => Boolean(entry.spawn_recommended))}`,
@@ -607,26 +606,6 @@ function metadataValue(file: string, label: string): string {
   return "";
 }
 
-function activeWorkstreams(workstreamDir: string): string {
-  if (!existsSync(workstreamDir)) return "- (none yet)";
-  const files = readdirMarkdown(workstreamDir).slice(0, 5);
-  if (files.length === 0) return "- (none yet)";
-
-  return files
-    .flatMap((file) => {
-      const status = metadataValue(file, "Status") || "unknown";
-      const currentSlice = metadataValue(file, "Current Slice") || "unknown";
-      const sourcePlan = metadataValue(file, "Source Plan") || "unknown";
-      return [
-        `- \`${file}\``,
-        `  - status: ${status}`,
-        `  - current_slice: ${currentSlice}`,
-        `  - source_plan: ${sourcePlan}`,
-      ];
-    })
-    .join("\n");
-}
-
 function readdirMarkdown(dir: string): string[] {
   try {
     return readdirSync(dir, { withFileTypes: true })
@@ -670,7 +649,6 @@ function renderContractBlock(args: Args): string {
   const architectureDomain = requireOption(args, "architectureDomain");
   const architectureCapability = requireOption(args, "architectureCapability");
   const architectureModule = requireOption(args, "architectureModule");
-  const workstreamDir = requireOption(args, "workstreamDir");
   const blockSlug = safeToken(functionalBlock);
   const latestSnapshot = findLatestMatchingFile("docs/architecture/snapshots", blockSlug, ".md");
   const latestHumanDiagram = findLatestMatchingFile("docs/architecture/diagrams", blockSlug, ".html");
@@ -707,16 +685,7 @@ function renderContractBlock(args: Args): string {
     `- Semantic diagram source: \`${semanticDiagramSource}\``,
     `- Latest human diagram: \`${latestHumanDiagram}\``,
     `- Pending architecture request: \`${requestFile}\``,
-    "",
-    "## Active Workstreams",
-    "",
-    activeWorkstreams(workstreamDir),
-    "",
-    "## Current Session Projection",
-    "",
-    `- Durable progress lives under \`${workstreamDir}\`.`,
-    "- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.",
-    "- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.",
+    "- Runtime progress authority: Forge Controller Home Requirement/Plan/Work/Evidence; this repository block contains authored architecture context only.",
     "<!-- END ARCHITECTURE CONTRACT -->",
     "",
   ].join("\n");

package/assets/templates/helpers/architecture-queue.sh

@@ -5,6 +5,7 @@ usage() {
   cat <<'USAGE_EOF'
 Usage:
   scripts/architecture-queue.sh record --file <path>
+  scripts/architecture-queue.sh resolve --file <docs/architecture/requests/file.md>
   scripts/architecture-queue.sh status [--format text|json|summary] [--gate]
   scripts/architecture-queue.sh reindex [--check] [--quiet]
   scripts/architecture-queue.sh triage --before <YYYY-MM-DD>
@@ -187,6 +188,48 @@ repo_relative_path() {
   printf '%s' "$value"
 }
 
+clear_contract_pending_request() {
+  local rel_request="$1"
+  local short_request="${rel_request#docs/architecture/}"
+  local context_file tmp
+
+  while IFS= read -r context_file; do
+    if ! grep -Fq "Pending architecture request: \`${rel_request}\`" "$context_file" &&
+       ! grep -Fq "Pending architecture request: \`${short_request}\`" "$context_file"; then
+      continue
+    fi
+    tmp="$(mktemp)"
+    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 }
+    ' "$context_file" > "$tmp"
+    mv "$tmp" "$context_file"
+    echo "[ArchitectureQueue] Cleared pending architecture request in ${context_file#./}"
+  done < <(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)
+}
+
+delete_request_file() {
+  local candidate="$1"
+  local rel_request
+  rel_request="$(repo_relative_path "$candidate" || true)"
+  if [[ -z "$rel_request" || "$(dirname "$rel_request")" != "$requests_dir" || "$rel_request" != "$requests_dir/"*.md ]]; then
+    echo "architecture-queue: resolve target must be a direct Markdown child of $requests_dir" >&2
+    return 2
+  fi
+  if [[ ! -f "$rel_request" ]]; then
+    echo "architecture-queue: request not found: $rel_request" >&2
+    return 2
+  fi
+  rm -- "$rel_request"
+  clear_contract_pending_request "$rel_request"
+}
+
 metadata_value() {
   local file="$1"
   local label="$2"
@@ -563,6 +606,20 @@ record_command() {
   echo "[ArchitectureDrift] severity=$severity capability_id=$capability_id functional_block=$functional_block spawn_recommended=$spawn_recommended contract_sync_required=$contract_sync_required"
 }
 
+resolve_command() {
+  if [[ -z "$file_path" ]]; then
+    echo "architecture-queue: resolve requires --file <docs/architecture/requests/file.md>" >&2
+    exit 2
+  fi
+  local rel_request
+  rel_request="$(repo_relative_path "$file_path" || true)"
+  delete_request_file "$rel_request"
+  quiet="true"
+  check_mode="false"
+  reindex_requests
+  echo "[ArchitectureQueue] Resolved $rel_request (deleted; Git history is the archive)"
+}
+
 triage_command() {
   if [[ -z "$before_date" ]]; then
     echo "architecture-queue: triage requires --before <YYYY-MM-DD>" >&2
@@ -597,16 +654,7 @@ triage_command() {
     capability_id="${capability_id:-root}"
     card="$(request_card_path "$capability_id")"
     architecture_event upsert-from-request --source-request "$request" --request-file "$card"
-    if [[ -x "scripts/archive-architecture-request.sh" ]]; then
-      bash scripts/archive-architecture-request.sh \
-        --request "$request" \
-        --status superseded \
-        --artifact "$card" \
-        --note "Merged into architecture queue card by triage --before $before_date." >/dev/null
-    else
-      mkdir -p "docs/architecture/requests/archive/$(date '+%Y')"
-      mv "$request" "docs/architecture/requests/archive/$(date '+%Y')/$(basename "$request")"
-    fi
+    delete_request_file "$request"
     count=$((count + 1))
   done < <(find "$requests_dir" -maxdepth 1 -type f -name '*.md' | sort)
 
@@ -627,6 +675,9 @@ case "$command_name" in
   record)
     record_command
     ;;
+  resolve)
+    resolve_command
+    ;;
   status)
     status_command
     ;;