# Shell Entrypoint DRY Audit and Node/Runtime Migration Plan

Date: 2026-05-17
Source chunk: chunk-000202-shell-entrypoint-dry-audit-node-runtime-migration-plan

## Snapshot

- Total shell scripts: 155
- Classified shell scripts: 155
- Unclassified shell scripts: 0
- Registry source: `ai/governance/registries/shell-entrypoints.yaml`
- Runtime proof command: `node ai/runtime/dist/cli.js shell-entrypoints --json`

## Classification Counts

- deprecated_compatibility_facade: 53
- bootstrap_recovery: 31
- guarded_mutation_owner: 30
- process_adapter: 17
- test_only: 17
- runtime_executor_facade: 7

## Keep As Shell

- Bootstrap/recovery wrappers should remain shell where they start, stop, or inspect tmux/process state:
  - `ai/runtime/start-daemon.sh`
  - `ai/runtime/stop-daemon.sh`
  - `ai/tools/local-dev/*.sh`
  - `ai/tools/dev-server/*.sh`
  - `ai/tools/runtime-supervisor/*.sh`
- Test-only shell fixtures may remain shell unless their assertions become complex enough to need typed Runtime APIs.

## Convert To Thin Runtime CLI Facade

- `ai/commands/validate.sh`: keep as the stable human/CI entrypoint, but move orchestration into a Runtime-owned Node validation runner in a follow-up. The chunk 000201 journal calls are acceptable as a thin CLI facade, but long-term command ordering/error handling belongs in Node.
- `ai/commands/workflow-state.sh`, `ai/commands/workflow-summary.sh`, and `ai/commands/orchestrator-next.sh`: keep compatibility wrappers, but prefer Runtime CLI/API implementations for state derivation.
- `ai/governance/validators/*.sh`: keep wrappers, but Runtime validator modules should remain canonical truth.

## Migrate To Node/TypeScript

- Telegram bridge delivery loop:
  - `ai/tools/telegram/bridge.sh`
  - `ai/tools/telegram/lib.sh`
  - Preserve shell start/stop/status wrappers, but migrate polling, outbox draining, send receipts, failed receipts, retry/backoff, and structured status to TypeScript.
- Approved-action dispatcher internals:
  - `ai/tools/approved-action-dispatcher/dispatch.sh`
  - Preserve dispatcher authority and shell compatibility while migrating parsing/reconciliation/status evidence to Runtime-owned TypeScript in small phases.
- Operator question/approval state helpers:
  - `ai/tools/operator-questions/*.sh`
  - Migrate state parsing and stale/consumed classification to Runtime modules; leave answer/request entrypoints guarded.

## Authority Sensitive: Do Not Touch Without Review

- `ai/commands/close-commit-approved.sh`
- `ai/tools/approved-action-dispatcher/*.sh`
- `ai/tools/operator-daemon/request-action.sh`
- `ai/tools/operator-daemon/actions/*.sh`
- `ai/tools/operator-questions/answer.sh`
- `ai/tools/operator-questions/register-approved-action.sh`
- `ai/tools/operator-questions/mark-approved-action-executed.sh`
- `ai/tools/operator-questions/resolve-approved-action.sh`

These paths own or guard lifecycle, close/commit, approval, dispatcher, daemon, or git side effects. Migration must preserve the existing authority owner and idempotency model.

## Low-Risk Change Completed

- Classified `ai/tools/operator-notifications/record-close-commit-contract.sh` in the registry so shell-entrypoint validation remains complete after chunk 000198.

## Follow-Up Chunks

- Runtime Validation Node Runner:
  - Convert `ai/commands/validate.sh` into a thin wrapper around a typed Runtime validation runner that records journal start/completed/failed events and handles service freshness before CLI-backed tests.
- Telegram Bridge TypeScript Runtime Service:
  - Continue the existing migration plan by moving delivery health/outbox drain into TypeScript while preserving shell process facades.
- Dispatcher TypeScript Reconciliation Adapter:
  - Add a Runtime-owned typed reader/reconciler for dispatcher records before moving execution logic.
- Operator Questions Typed State Adapter:
  - Migrate list/status/stale classification to Runtime modules while preserving guarded answer and approved-action mutation wrappers.

## Carry Forward

No new CFD is required. Existing pending/enforcement items already cover:

- cfd-0004: legacy Telegram TSV projection remains.
- cfd-0005: compatibility-only manual lifecycle mutation paths remain.
- cfd-0020: assistant final chat summary enforcement remains policy-bound.