@moretea-labs/forge 1.7.2 → 1.8.0

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
     ;;

package/assets/templates/helpers/archive-workflow.sh

@@ -13,44 +13,12 @@ fi
 usage() {
   cat <<'USAGE_EOF'
 Usage: scripts/archive-workflow.sh --plan <plan-file> --outcome <Completed|Abandoned|Superseded>
-USAGE_EOF
-}
-
-set_plan_status() {
-  local file="$1"
-  local status="$2"
-  local tmp_file
-  tmp_file="$(mktemp)"
-  awk -v next_status="$status" '
-    BEGIN { updated = 0 }
-    {
-      if (!updated && $0 ~ /\*\*Status\*\*:/) {
-        sub(/\*\*Status\*\*: .*/, "**Status**: " next_status)
-        updated = 1
-      }
-      print
-    }
-  ' "$file" > "$tmp_file"
-  mv "$tmp_file" "$file"
-}
 
-unique_archive_path() {
-  local desired="$1"
-  if [[ ! -e "$desired" ]]; then
-    printf '%s' "$desired"
-    return
-  fi
-
-  local stem ext counter candidate
-  stem="${desired%.md}"
-  ext=".md"
-  counter=2
-  candidate="${stem}-v${counter}${ext}"
-  while [[ -e "$candidate" ]]; do
-    counter=$((counter + 1))
-    candidate="${stem}-v${counter}${ext}"
-  done
-  printf '%s' "$candidate"
+Compatibility name: this helper closes a terminal repo-local workflow. It does
+not create repository archive files. The final plan/contract/review/notes must
+already be represented by HEAD with no staged or unstaged changes; after that
+proof, the helper deletes those lifecycle artifacts and relies on Git history.
+USAGE_EOF
 }
 
 normalize_slug() {
@@ -59,9 +27,7 @@ normalize_slug() {
 
 is_transient_plan_slug() {
   case "$1" in
-    think-plan-[0-9]*|codex-plan-[0-9]*|approved-plan-[0-9]*)
-      return 0
-      ;;
+    think-plan-[0-9]*|codex-plan-[0-9]*|approved-plan-[0-9]*) return 0 ;;
   esac
   return 1
 }
@@ -104,53 +70,52 @@ plan_artifact_stem_from_parts() {
   fi
 }
 
-todo_is_deferred_ledger() {
-  local file="${1:-tasks/todos.md}"
-  [[ -f "$file" ]] || return 1
-  grep -Eq '^# Deferred Goal Ledger[[:space:]]*$' "$file" \
-    && grep -Eq '^> \*\*Status\*\*:[[:space:]]*Backlog[[:space:]]*$' "$file" \
-    && grep -Eq '^## Deferred Goals[[:space:]]*$' "$file" \
-    && grep -Eq '\|[[:space:]]*Goal[[:space:]]*\|[[:space:]]*Why Deferred[[:space:]]*\|[[:space:]]*Tradeoff[[:space:]]*\|[[:space:]]*Revisit Trigger[[:space:]]*\|' "$file"
+repo_relative_path() {
+  local candidate="$1"
+  python3 - "$candidate" <<'PY'
+from pathlib import Path
+import sys
+root = Path.cwd().resolve()
+path = Path(sys.argv[1])
+if not path.is_absolute():
+    path = root / path
+try:
+    print(path.resolve().relative_to(root).as_posix())
+except ValueError:
+    raise SystemExit(2)
+PY
 }
 
-touch_deferred_ledger_update_marker() {
-  local file="${1:-tasks/todos.md}"
-  local tmp_file
-  tmp_file="$(mktemp)"
-  awk '
-    BEGIN { updated = 0 }
-    !updated && /^> \*\*Updated\*\*:/ {
-      print "> **Updated**: (archive-workflow)"
-      updated = 1
-      next
-    }
-    { print }
-  ' "$file" > "$tmp_file"
-  mv "$tmp_file" "$file"
-}
-
-write_empty_deferred_ledger() {
-  cat > tasks/todos.md <<'TODO_EOF'
-# Deferred Goal Ledger
-
-> **Status**: Backlog
-> **Updated**: (archive-workflow)
-> **Scope**: Medium/long-term goals deferred from active plan execution
-
-Current plan tasks live in the active plan's `## Task Breakdown`.
-Do not duplicate that execution checklist here. Record only work intentionally deferred beyond this slice, with the tradeoff and revisit trigger.
-
-## Deferred Goals
-
-| Goal | Why Deferred | Tradeoff | Revisit Trigger |
-|------|--------------|----------|-----------------|
-| (none) | Archived workflow did not leave a deferred medium/long-term goal. | Keep the next slice clean. | Add a row when a real follow-up is postponed. |
-TODO_EOF
+assert_history_safe() {
+  local candidate="$1"
+  local rel
+  [[ -f "$candidate" ]] || return 0
+  rel="$(repo_relative_path "$candidate" || true)"
+  [[ -n "$rel" ]] || {
+    echo "archive-workflow: refusing path outside repository: $candidate" >&2
+    return 1
+  }
+  git ls-files --error-unmatch -- "$rel" >/dev/null 2>&1 || {
+    echo "archive-workflow: refusing to delete untracked lifecycle artifact: $rel" >&2
+    echo "Persist or deliberately discard the unique content before workflow closeout." >&2
+    return 1
+  }
+  git cat-file -e "HEAD:$rel" 2>/dev/null || {
+    echo "archive-workflow: refusing to delete lifecycle artifact not represented by HEAD: $rel" >&2
+    return 1
+  }
+  git diff --quiet -- "$rel" || {
+    echo "archive-workflow: refusing to delete lifecycle artifact with unstaged changes: $rel" >&2
+    return 1
+  }
+  git diff --cached --quiet -- "$rel" || {
+    echo "archive-workflow: refusing to delete lifecycle artifact with staged changes: $rel" >&2
+    return 1
+  }
 }
 
 plan_file=""
 outcome=""
-
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --plan)
@@ -175,120 +140,65 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
-if [[ -z "$plan_file" || -z "$outcome" ]]; then
-  echo "--plan and --outcome are required" >&2
-  usage
-  exit 1
-fi
-
+[[ -n "$plan_file" && -n "$outcome" ]] || { echo "--plan and --outcome are required" >&2; usage; exit 1; }
 case "$outcome" in
-  Completed|Abandoned|Superseded)
-    ;;
-  *)
-    echo "Invalid outcome: $outcome" >&2
-    exit 1
-    ;;
+  Completed|Abandoned|Superseded) ;;
+  *) echo "Invalid outcome: $outcome" >&2; exit 1 ;;
 esac
+[[ -f "$plan_file" ]] || { echo "Plan file not found: $plan_file" >&2; exit 1; }
 
-if [[ ! -f "$plan_file" ]]; then
-  echo "Plan file not found: $plan_file" >&2
-  exit 1
-fi
-
-normalized_plan="${plan_file#./}"
-if [[ "$normalized_plan" == plans/archive/* ]]; then
-  echo "Error: plan is already archived" >&2
-  exit 1
-fi
-
-mkdir -p plans/archive tasks/archive tasks/notes
+normalized_plan="$(repo_relative_path "$plan_file" || true)"
+case "$normalized_plan" in
+  plans/*.md) ;;
+  *) echo "archive-workflow: plan must be a direct Markdown child of plans/: $plan_file" >&2; exit 1 ;;
+esac
 
-timestamp="$(date +%Y%m%d-%H%M)"
-timestamp_human="$(date '+%Y-%m-%d %H:%M')"
-plan_base="$(basename "$plan_file")"
-slug="$(echo "$plan_base" | sed -E 's/^plan-[0-9]{8}-[0-9]{4}-//; s/\.md$//')"
+plan_base="$(basename "$normalized_plan")"
+slug="$(printf '%s' "$plan_base" | sed -E 's/^plan-[0-9]{8}-[0-9]{4}-//; s/\.md$//')"
 original_artifact_stem="$(printf '%s' "$plan_base" | sed -E 's/^plan-//; s/\.md$//')"
-artifact_stem="$(plan_artifact_stem_from_parts "$plan_file" "$original_artifact_stem" "$slug")"
-parent_run_id="${HOOK_RUN_ID:-${CLAUDE_RUN_ID:-${CODEX_RUN_ID:-run-${timestamp}}}}"
-todo_source_plan="$(awk -F': ' '/^> \*\*Source Plan\*\*:/ {print $2; exit}' tasks/todos.md 2>/dev/null | xargs)"
-
-plan_status="Archived"
-if [[ "$outcome" == "Abandoned" ]]; then
-  plan_status="Abandoned"
-fi
-set_plan_status "$plan_file" "$plan_status"
-
-archive_plan_path="plans/archive/${plan_base}"
-archive_plan_path="$(unique_archive_path "$archive_plan_path")"
-
-if [[ "$plan_file" != "$archive_plan_path" ]]; then
-  mv "$plan_file" "$archive_plan_path"
-fi
-
-if [[ -f tasks/todos.md ]] && grep -q '[^[:space:]]' tasks/todos.md; then
-  archive_todo="tasks/archive/todo-${timestamp}-${slug}.md"
-  {
-    echo "> **Archived**: ${timestamp_human}"
-    echo "> **Related Plan**: ${archive_plan_path}"
-    echo "> **Outcome**: ${outcome}"
-    echo "> **Source Plan**: ${todo_source_plan:-"(none)"}"
-    echo "> **Parent Run ID**: ${parent_run_id}"
-    echo
-    cat tasks/todos.md
-  } > "$archive_todo"
-fi
+artifact_stem="$(plan_artifact_stem_from_parts "$normalized_plan" "$original_artifact_stem" "$slug")"
+
+candidates=("$normalized_plan")
+for path in \
+  "tasks/contracts/${artifact_stem}.contract.md" \
+  "tasks/reviews/${artifact_stem}.review.md" \
+  "tasks/notes/${artifact_stem}.notes.md" \
+  "tasks/contracts/${slug}.contract.md" \
+  "tasks/reviews/${slug}.review.md" \
+  "tasks/notes/${slug}.notes.md"; do
+  [[ -f "$path" ]] && candidates+=("$path")
+done
 
-notes_file="tasks/notes/${artifact_stem}.notes.md"
-if [[ ! -f "$notes_file" && -f "tasks/notes/${slug}.notes.md" ]]; then
-  notes_file="tasks/notes/${slug}.notes.md"
-fi
-if [[ -f "$notes_file" ]]; then
-  archive_notes="$(unique_archive_path "tasks/archive/notes-${timestamp}-${slug}.md")"
-  {
-    echo "> **Archived**: ${timestamp_human}"
-    echo "> **Related Plan**: ${archive_plan_path}"
-    echo "> **Outcome**: ${outcome}"
-    echo "> **Lifecycle**: notes"
-    echo "> **Parent Run ID**: ${parent_run_id}"
-    echo
-    cat "$notes_file"
-  } > "$archive_notes"
-  rm -f "$notes_file"
-fi
+# All-or-nothing preflight. Git history is only a valid archive after the exact
+# terminal evidence has been committed; never silently erase unique local work.
+for path in "${candidates[@]}"; do
+  assert_history_safe "$path"
+done
 
-if todo_is_deferred_ledger tasks/todos.md; then
-  touch_deferred_ledger_update_marker tasks/todos.md
-else
-  write_empty_deferred_ledger
-fi
+# Avoid deleting the same fallback artifact twice.
+declare -A seen=()
+for path in "${candidates[@]}"; do
+  [[ -n "${seen[$path]:-}" ]] && continue
+  seen[$path]=1
+  rm -- "$path"
+  echo "[WorkflowCloseout] Removed $path"
+done
 
-# Clear active-plan markers if they pointed to the archived plan
-cleared_active=0
 for marker_file in ".ai/harness/active-plan" ".claude/.active-plan"; do
-  if [[ ! -f "$marker_file" ]]; then
-    continue
-  fi
+  [[ -f "$marker_file" ]] || continue
   marker_value="$(cat "$marker_file" 2>/dev/null | xargs)"
-  if [[ "$marker_value" == "$plan_file" || "$marker_value" == "./$plan_file" ]]; then
+  if [[ "$marker_value" == "$normalized_plan" || "$marker_value" == "./$normalized_plan" || "$marker_value" == "$plan_file" ]]; then
     rm -f "$marker_file"
-    cleared_active=1
-    echo "Cleared $marker_file (archived plan was active)"
+    echo "[WorkflowCloseout] Cleared $marker_file"
   fi
 done
-if [[ "$cleared_active" -eq 1 ]]; then
-  rm -f ".ai/harness/active-worktree"
-fi
+rm -f ".ai/harness/active-worktree"
 
-# Clean up saved plan state backups
-plan_key="$(basename "$plan_file" .md)"
-rm -f ".claude/.plan-state/${plan_key}.todo.md.bak"
-rm -f ".claude/.plan-state/${plan_key}.task-state.json.bak"
+plan_key="$(basename "$normalized_plan" .md)"
+rm -f ".claude/.plan-state/${plan_key}.todo.md.bak" ".claude/.plan-state/${plan_key}.task-state.json.bak"
 
 if [[ -x "scripts/refresh-current-status.sh" ]]; then
-  bash "scripts/refresh-current-status.sh" --clear --write --reason "archive-workflow" || true
+  bash "scripts/refresh-current-status.sh" --clear --write --reason "workflow-closeout" || true
 fi
 
-echo "Archived plan to: $archive_plan_path"
-if [[ -f "docs/reference-configs/handoff-protocol.md" ]]; then
-  echo "Next: refresh or prune long-running workflow rules using docs/reference-configs/handoff-protocol.md"
-fi
+echo "[WorkflowCloseout] Closed $normalized_plan as outcome=$outcome; Git history is the archive."

package/assets/templates/helpers/capability-config.ts

@@ -15,7 +15,8 @@ type Capability = {
   prefixes: string[];
   contract_files: ContractFiles;
   architecture_module: string;
-  workstream_dir: string;
+  /** Legacy migration metadata; new capability config never writes it. */
+  workstream_dir?: string;
   lsp_profile: string;
   verification_hints: string[];
 };
@@ -64,12 +65,12 @@ function usage(): never {
       "  --agents <path>                  AGENTS.md path (default: <prefix>/AGENTS.md)",
       "  --claude <path>                  CLAUDE.md path (default: <prefix>/CLAUDE.md)",
       "  --architecture-module <path>     Architecture module path",
-      "  --workstream-dir <path>          Workstream directory path",
+      "  --workstream-dir <path>          RETIRED: repo-local Workstreams are no longer writable",
       "  --lsp-profile <profile>          LSP/tooling profile (default: typescript-lsp)",
       "  --verification-hint <command>    Repeatable local verification hint",
       "  --create-prefix                  Create the prefix directory when missing",
       "  --create-architecture-module     Create a minimal architecture module when missing",
-      "  --create-workstream              Create a durable workstream ledger",
+      "  --create-workstream              RETIRED: use Controller Home Requirement/Plan/Work",
       "  --no-sync-contracts              Only update the registry",
       "  --dry-run                        Print planned changes without writing",
       "  --format text|json               Output format (default: text)",
@@ -238,7 +239,6 @@ function buildCapability(args: Args, repo: string): Capability {
       args.architectureModule || `docs/architecture/modules/${domain}/${name}.md`,
       repo
     ),
-    workstream_dir: normalizeRepoPath(args.workstreamDir || `tasks/workstreams/${domain}/${name}`, repo),
     lsp_profile: args.lspProfile,
     verification_hints:
       args.verificationHints.length > 0 ? args.verificationHints : ["record local commands here before implementation"],
@@ -304,7 +304,7 @@ function syncContracts(repo: string, capability: Capability): void {
     architecture_domain: capability.domain,
     architecture_capability: capability.name,
     architecture_module: capability.architecture_module,
-    workstream_dir: capability.workstream_dir,
+    ...(capability.workstream_dir ? { workstream_dir: capability.workstream_dir } : {}),
     contract_agents: capability.contract_files.agents,
     contract_claude: capability.contract_files.claude,
     lsp_profile: capability.lsp_profile,
@@ -341,12 +341,11 @@ function createArchitectureModule(repo: string, capability: Capability): void {
   );
 }
 
-function createWorkstream(repo: string, capability: Capability): void {
-  runChecked(repo, "bash", ["scripts/workstream-sync.sh", "ensure", "--block", capability.prefixes[0]]);
-}
-
 function main(): void {
   const args = parseArgs(process.argv.slice(2));
+  if (args.workstreamDir || args.createWorkstream) {
+    throw new Error("LEGACY_WORKSTREAM_WRITES_RETIRED: repo-local tasks/workstreams are migration-only; use Forge Controller Home Requirement/Plan/Work");
+  }
   const repo = repoRoot(args.repo);
   const requestedCapability = buildCapability(args, repo);
   const prefixPath = resolve(repo, requestedCapability.prefixes[0]);
@@ -366,14 +365,12 @@ function main(): void {
 
   if (args.syncContracts) actions.push(`sync-contracts:${capability.contract_files.agents},${capability.contract_files.claude}`);
   if (args.createArchitectureModule) actions.push(`create-architecture-module:${capability.architecture_module}`);
-  if (args.createWorkstream) actions.push(`create-workstream:${capability.workstream_dir}`);
   actions.push("validate:capability-registry");
 
   if (!args.dryRun) {
     if (status === "added") writeRegistry(repo, registry);
     if (args.syncContracts) syncContracts(repo, capability);
     if (args.createArchitectureModule) createArchitectureModule(repo, capability);
-    if (args.createWorkstream) createWorkstream(repo, capability);
     validateRegistry(repo);
   }
 

package/assets/templates/helpers/capability-resolver.ts

@@ -15,7 +15,8 @@ type Capability = {
   prefixes: string[];
   contract_files: ContractFiles;
   architecture_module: string;
-  workstream_dir: string;
+  /** Legacy migration metadata only. Modern capability authority uses Controller Home Work. */
+  workstream_dir?: string;
   lsp_profile: string;
   verification_hints: string[];
 };
@@ -25,7 +26,7 @@ type CapabilityRegistry = {
   capabilities: Capability[];
 };
 
-type Format = "json" | "text" | "prefixes";
+type Format = "json" | "text" | "prefixes" | "ids";
 
 type Args = {
   command: string;
@@ -42,8 +43,8 @@ function usage(): never {
     [
       "Usage:",
       "  scripts/capability-resolver.ts list [--repo <repo>] [--format json|text|prefixes]",
-      "  scripts/capability-resolver.ts match --path <repo-relative-path> [--repo <repo>] [--format json|text]",
-      "  scripts/capability-resolver.ts match --paths-from <file|-> [--repo <repo>] [--format json|text]",
+      "  scripts/capability-resolver.ts match --path <repo-relative-path> [--repo <repo>] [--format json|text|ids]",
+      "  scripts/capability-resolver.ts match --paths-from <file|-> [--repo <repo>] [--format json|text|ids]",
       "  scripts/capability-resolver.ts validate [--repo <repo>] [--format json|text]",
     ].join("\n")
   );
@@ -73,7 +74,7 @@ function parseArgs(argv: string[]): Args {
         break;
       case "--format": {
         const value = argv[++index] as Format;
-        if (!["json", "text", "prefixes"].includes(value)) usage();
+        if (!["json", "text", "prefixes", "ids"].includes(value)) usage();
         args.format = value;
         break;
       }
@@ -91,6 +92,7 @@ function parseArgs(argv: string[]): Args {
   if (args.command === "match" && !args.path && !args.pathsFrom) usage();
   if (args.command === "match" && args.path && args.pathsFrom) usage();
   if (args.command === "match" && args.format === "prefixes") usage();
+  if (args.command !== "match" && args.format === "ids") usage();
   return args;
 }
 
@@ -151,7 +153,6 @@ function defaultCapabilityForPrefix(prefix: string): Capability {
       claude: `${prefix}/CLAUDE.md`,
     },
     architecture_module: `docs/architecture/modules/${domain}/${name}.md`,
-    workstream_dir: `tasks/workstreams/${domain}/${name}`,
     lsp_profile: "typescript-lsp",
     verification_hints: ["record local commands here before implementation"],
   };
@@ -220,7 +221,6 @@ function validateCapability(capability: Capability, repo: string): string[] {
     ["domain", capability.domain],
     ["name", capability.name],
     ["architecture_module", capability.architecture_module],
-    ["workstream_dir", capability.workstream_dir],
     ["lsp_profile", capability.lsp_profile],
   ];
 
@@ -260,14 +260,20 @@ function validateCapability(capability: Capability, repo: string): string[] {
     }
   }
 
-  for (const [field, value] of [
-    ["architecture_module", capability.architecture_module],
-    ["workstream_dir", capability.workstream_dir],
-  ] as const) {
-    try {
-      normalizeRepoPath(value, repo);
-    } catch (error) {
-      errors.push(`${capability.id}: invalid ${field}: ${(error as Error).message}`);
+  try {
+    normalizeRepoPath(capability.architecture_module, repo);
+  } catch (error) {
+    errors.push(`${capability.id}: invalid architecture_module: ${(error as Error).message}`);
+  }
+  if (capability.workstream_dir !== undefined) {
+    if (typeof capability.workstream_dir !== "string" || capability.workstream_dir.trim() === "") {
+      errors.push(`${capability.id}: legacy workstream_dir must be a non-empty repository path when present`);
+    } else {
+      try {
+        normalizeRepoPath(capability.workstream_dir, repo);
+      } catch (error) {
+        errors.push(`${capability.id}: invalid legacy workstream_dir: ${(error as Error).message}`);
+      }
     }
   }
 
@@ -312,10 +318,16 @@ function validateRegistry(registry: CapabilityRegistry, repo: string): string[]
 
     try {
       architectureModules.add(normalizeRepoPath(capability.architecture_module, repo));
-      workstreamDirs.add(normalizeRepoPath(capability.workstream_dir, repo));
     } catch {
       // Field-specific validation already recorded the concrete error.
     }
+    if (capability.workstream_dir) {
+      try {
+        workstreamDirs.add(normalizeRepoPath(capability.workstream_dir, repo));
+      } catch {
+        // Legacy field-specific validation already recorded the concrete error.
+      }
+    }
   }
 
   const modulesRoot = resolve(repo, "docs/architecture/modules");
@@ -338,7 +350,9 @@ function validateRegistry(registry: CapabilityRegistry, repo: string): string[]
   }
 
   const workstreamsRoot = resolve(repo, "tasks/workstreams");
-  if (existsSync(workstreamsRoot)) {
+  // Only legacy registries that still declare workstream ownership participate
+  // in orphan validation. Modern registries do not synthesize this retired surface.
+  if (workstreamDirs.size > 0 && existsSync(workstreamsRoot)) {
     const stack = [workstreamsRoot];
     while (stack.length > 0) {
       const current = stack.pop()!;
@@ -383,7 +397,6 @@ function findMatch(registry: CapabilityRegistry, repo: string, inputPath: string
       architecture_domain: "root",
       architecture_capability: "_root",
       architecture_module: "docs/architecture/index.md",
-      workstream_dir: "tasks/workstreams/root/_root",
     };
   }
 
@@ -409,7 +422,7 @@ function findMatch(registry: CapabilityRegistry, repo: string, inputPath: string
     architecture_domain: winner.capability.domain,
     architecture_capability: winner.capability.name,
     architecture_module: winner.capability.architecture_module,
-    workstream_dir: winner.capability.workstream_dir,
+    ...(winner.capability.workstream_dir ? { workstream_dir: winner.capability.workstream_dir } : {}),
     contract_agents: winner.capability.contract_files.agents,
     contract_claude: winner.capability.contract_files.claude,
     lsp_profile: winner.capability.lsp_profile,
@@ -475,6 +488,9 @@ async function main(): Promise<void> {
     }
     if (args.format === "json") {
       printJson(matches);
+    } else if (args.format === "ids") {
+      const ids = [...new Set(matches.map((match) => match.capability_id))].sort();
+      for (const id of ids) console.log(id);
     } else {
       for (const match of matches) {
         console.log(`${match.file_path}: ${match.capability_id} (${match.matched_prefix})`);
@@ -486,6 +502,8 @@ async function main(): Promise<void> {
   const match = findMatch(registry, repo, args.path);
   if (args.format === "json") {
     printJson(match);
+  } else if (args.format === "ids") {
+    console.log(match.capability_id);
   } else {
     for (const [key, value] of Object.entries(match)) {
       if (Array.isArray(value)) {