Semantic Delta Log
This page records which re-foundation changes preserved DreamCLI behavior versus which ones intentionally changed it.
Use it as the semantic review anchor for:
- release notes and changelog drafting;
- follow-up docs like rationale, migration, and troubleshooting;
- refactor review when code motion and user-visible behavior happen together.
It is not a public API contract. It is a maintained execution-semantics log for the dreamcli-re-foundation workstream.
Preserved Semantics
These behaviors were intentionally kept stable while internal ownership moved.
| Surface | Preserved behavior | Evidence | Notes |
|---|---|---|---|
| Planner and dispatch | Root --help, root --version, default-command fallback, nested dispatch, and propagated-flag masking stay the same. | CLI Semantics, src/core/cli/planner.test.ts, src/core/cli/cli-dispatch.test.ts | Planner extraction changed ownership, not user-facing dispatch rules. |
| Resolution precedence | Flag precedence stays CLI -> env -> config -> prompt -> default. Arg precedence stays CLI -> stdin -> env -> default for opted-in args. | CLI Semantics, src/core/resolve/contracts.test.ts, src/core/resolve/index.ts | Resolver refactors and module splits were constrained to preserve source order and prompt/stdin gating. |
| Execution lifecycle | Parse -> resolve -> hooks -> derive/middleware -> action -> result assembly still runs in the same semantic order, with cleanup on success, help exits, and failures. | src/core/testkit/executor-contract.test.ts, src/core/execution/index.ts | Centralizing execution in src/core/execution/ changed ownership, not lifecycle guarantees. |
| Output policy behavior | JSON routing, TTY-aware decorative-output suppression, and activity cleanup semantics stay stable across the output-policy split. | Output Contract, src/core/output/contracts.test.ts, src/core/output/output.test.ts | The re-foundation extracted policy seams without widening the public Out behavior. |
| Completion planner behavior | Nested command completion, propagated ancestor flags, and root/default-command completion rules remain contract-tested while shell support expanded. | Shell Completions, src/core/cli/cli-completion-contract.test.ts, src/core/completion/completion.test.ts | New shells were added without inventing a separate completion planner model. |
Intentional Redesigns
These are the main semantic deltas the re-foundation intentionally introduced.
| Delta | Before | Now | Evidence | Why |
|---|---|---|---|---|
| Canonical execution ownership | The real parse -> resolve -> execute pipeline was effectively owned by runCommand() even though CLI also orchestrated parts of it. | src/core/execution/index.ts is the explicit canonical executor. CLI and testkit both delegate to that shared seam. | src/core/execution/index.ts, src/core/cli/index.ts, src/core/testkit/index.ts, docs/reference/support-matrix.md | One owned execution path makes future planner, resolver, and output changes easier to localize and test. |
| Resolver aggregate diagnostics | Mixed flag/arg validation failures were aggregated, but the top-level diagnostic was weaker and less source-aware. | Aggregate validation errors now carry per-issue summaries with normalized labels like flag --port and argument <count> plus source labels like env PORT and stdin. | src/core/resolve/resolve-aggregation.test.ts, src/core/resolve/errors.ts, Resolver Contract | This improved the user-facing failure story without breaking nested ValidationError JSON used by existing tests and consumers. |
| Completion support truth | The type/docs surface was broader than reality and only bash plus zsh were actually shipped. | fish and powershell completion generation are now shipped, tested, and reflected consistently across docs and support-truth surfaces. | src/core/completion/shells/fish.ts, src/core/completion/shells/powershell.ts, src/core/cli/cli-completion-contract.test.ts, Support Matrix | The supported shell surface is now truthful across code, tests, and docs instead of relying on a wider union type or deferred claims. |
Remaining Deferred
These areas are still intentionally deferred and should not be described as shipped semantic changes yet.
| Area | Current state | Tracking |
|---|---|---|
| Broader CI/runtime-shell coverage claims | Runtime support is shipped, but broader cross-platform CI coverage is still not claimed as complete. | Support Matrix, harden-ci-coverage |
Narrative Follow-Through
The post-stabilization narrative docs set is now published: