@tdk-landscape/tdk-cli-core 1.3.53 → 1.3.55

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/design.md

@@ -1,102 +0,0 @@
-## Context
-
-TDK CLI manages local microservice development through project, stack, resource, doctor, status, and Tilt-oriented commands. The current developer workflow is terminal-heavy: developers run commands manually, inspect logs across tools, and infer root causes from mixed CLI, Docker, Bun, Tilt, port, and config output.
-
-The MVP introduces a VS Code-only extension in a new repository/package at `/private/var/www/2025/ollamar1/tdk-vscode-extension` that treats the TDK CLI as the operational backend. The extension should not fork orchestration logic from the CLI. It should call the CLI, parse structured output where available, preserve raw output for debugging, and present a focused editor-native workflow for orchestration and troubleshooting.
-
-Stakeholders are TDK CLI maintainers, developers using TDK-managed repositories, and maintainers who need failure reports with enough context to debug quickly.
-
-## Goals / Non-Goals
-
-**Goals:**
-
-- Provide a VS Code extension MVP that can be developed and versioned separately from the CLI.
-- Deliver a runnable one-shot implementation with scaffold, source code, tests, documentation, and a verification record.
-- Detect TDK projects and expose project, stack, resource, doctor, status, and lifecycle actions from VS Code.
-- Provide a real troubleshooting flow that classifies failures, shows likely causes, links evidence, and offers safe next actions.
-- Manage notifications so background monitoring is useful without becoming noisy.
-- Document CLI JSON/status output gaps as follow-up work without changing the TDK CLI during this MVP.
-- Include a spec critique and final requirement trace before implementation is considered complete.
-
-**Non-Goals:**
-
-- Support JetBrains, Vim, browser IDEs, or a standalone Electron IDE in the MVP.
-- Replace the Tilt UI or reimplement Tilt orchestration.
-- Automatically run destructive or state-changing repairs without explicit user confirmation.
-- Build a full AI assistant or free-form chat interface in the first release.
-- Add remote/team dashboard features, cloud sync, or marketplace publishing automation in the MVP.
-- Modify the TDK CLI command contract in the MVP.
-
-## Decisions
-
-1. Create a new extension repo/package at `/private/var/www/2025/ollamar1/tdk-vscode-extension`.
-
-   Rationale: VS Code extension packaging, activation lifecycle, tests, and release cadence differ from the CLI. A separate package keeps the CLI focused and allows extension-specific dependencies such as `@types/vscode`, `vsce`, and VS Code test harnesses.
-
-   Alternative considered: place the extension under `tdk-cli-core/ext`. That is quicker initially, but it risks coupling extension release mechanics to CLI internals and makes it harder to ship independently. For one-shot implementation, the location is fixed to avoid blocking on repository placement.
-
-2. Use the TDK CLI as the source of truth.
-
-   Rationale: The extension should orchestrate and troubleshoot through commands such as `tdk doctor`, `tdk status`, `tdk stacks`, `tdk resources`, `tdk up`, and `tdk down`. This avoids two implementations of project discovery, stack/resource state, and health logic.
-
-   Alternative considered: read config files and Tilt state directly from the extension. That may be needed for display hints, but it must not become the primary orchestration model.
-
-   One-shot constraint: do not modify the CLI during the MVP. If structured output is incomplete, implement resilient adapters that keep raw output available and document the missing CLI contract in `docs/cli-contract-gaps.md`.
-
-3. Introduce a command runner boundary.
-
-   Rationale: A typed command runner can capture command, cwd, stdout, stderr, exit code, duration, cancellation, and parsed JSON payloads. This gives orchestration, troubleshooting, tests, and notifications a shared event model.
-
-   Alternative considered: run commands ad hoc from each UI command. That would make troubleshooting weaker because failures would lack consistent metadata.
-
-4. Build troubleshooting as deterministic rules first.
-
-   Rationale: The MVP needs reliable, reviewable classification for common failures: missing TDK CLI, unsupported CLI version, non-TDK workspace, Docker daemon unavailable, Tilt unavailable, Bun unavailable, occupied ports, invalid or missing master config, invalid service manifest, failed health endpoint, duplicate daemon, and Tilt startup failures.
-
-   Alternative considered: use an LLM-based troubleshooter first. That would be flashy but harder to test and risky for repair suggestions. LLM assistance can be considered later once deterministic evidence capture is solid.
-
-5. Use quiet-by-default notification policy.
-
-   Rationale: Background status checks can easily become spam. The extension should deduplicate repeated failures, escalate only when state changes or user action is required, and let users tune categories such as doctor failures, stack failures, and repair completion.
-
-   Alternative considered: notify on every failed poll. That is easier, but it teaches users to ignore the extension.
-
-6. Keep repair actions explicit and safe.
-
-   Rationale: Troubleshooting can recommend actions such as opening logs, rerunning doctor, starting Docker docs, freeing a port guide, regenerating configs, or running a specific TDK command. Any command that changes project files, starts/stops services, prunes Docker, or modifies config must require explicit confirmation and show the exact command.
-
-   Alternative considered: one-click auto-fix for every known issue. That is too risky for an MVP in developer workspaces.
-
-7. Ship three concrete VS Code surfaces.
-
-   Rationale: A one-shot MVP needs enough UI to prove value without becoming a full IDE. The required surfaces are a TDK Explorer tree, a Troubleshooter view, and a TDK output channel. Commands can be exposed through command palette and tree actions.
-
-   Alternative considered: command palette only. That is faster, but too weak to satisfy the orchestration and notification requirements.
-
-## Risks / Trade-offs
-
-- CLI output is not structured enough for robust parsing -> Use conservative parsing and mocked adapters for tests, preserve raw output, and document gaps for a later CLI change.
-- Extension becomes a thin command palette wrapper -> Require project tree views, status surfaces, troubleshooter evidence, and notification policy as MVP acceptance criteria.
-- Troubleshooter over-promises root cause accuracy -> Display confidence, evidence, and next safe step rather than pretending every issue has a single guaranteed cause.
-- Notifications become noisy -> Deduplicate by issue fingerprint, workspace, resource, severity, and state transition.
-- New repo setup slows the first implementation -> Generate a minimal VS Code TypeScript extension scaffold with focused tests before expanding UI.
-- Repair actions could damage local state -> Require confirmation for all state-changing actions and block destructive commands from automatic execution.
-
-## Migration Plan
-
-1. Scaffold `/private/var/www/2025/ollamar1/tdk-vscode-extension` with TypeScript, VS Code engine constraints, test harness, linting, and basic activation.
-2. Implement the command runner and workspace detector against the installed or workspace-local TDK CLI.
-3. Add orchestration commands and tree/status views for projects, stacks, and resources.
-4. Add deterministic diagnostic rules and the troubleshooter webview/tree/detail UI.
-5. Add notification policy, deduplication, and user settings.
-6. Document missing CLI structured-output gaps without changing the CLI.
-7. Run spec critique, implementation review, automated tests, and manual VS Code smoke tests.
-
-Rollback is simple for the MVP: disable or uninstall the VS Code extension. Follow-up CLI structured-output improvements, if implemented after this MVP, must be additive and preserve existing command behavior.
-
-## Fixed MVP Answers
-
-- Repository path: `/private/var/www/2025/ollamar1/tdk-vscode-extension`.
-- Minimum CLI version: detect and display the installed CLI version when available; do not enforce a minimum version in the MVP unless the CLI command is missing.
-- Repair actions: support command suggestions and confirmed command execution for safe, explicit commands only.
-- Notification history: use VS Code native notifications plus the Troubleshooter view as the persistent issue history.

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/proposal.md

@@ -1,31 +0,0 @@
-## Why
-
-TDK CLI already provides project, stack, resource, health, and Tilt orchestration commands, but developers still have to leave the editor to understand what is running, why something failed, and what to do next. A VS Code-only plugin can turn the CLI into an operational cockpit with guided troubleshooting, clearer failure notifications, and one-click orchestration for the common local development loop.
-
-## What Changes
-
-- Create a new VS Code extension repository/package at `/private/var/www/2025/ollamar1/tdk-vscode-extension` for a TDK IDE plugin instead of embedding extension code in the CLI package.
-- Add VS Code commands and panels for TDK project detection, stack/resource orchestration, status inspection, logs, and doctor checks.
-- Add a real troubleshooter that classifies common TDK/Tilt/Docker/Bun/port/config failures, explains likely causes, and offers safe, explicit repair actions.
-- Add notification management so normal background polling remains quiet, while actionable failures surface with deduplicated severity, context, and next steps.
-- Add an implementation review workflow that validates the shipped extension against every requirement and records critique findings before the one-shot MVP is considered done.
-
-## Capabilities
-
-### New Capabilities
-
-- `vscode-tdk-orchestration`: VS Code extension behavior for detecting TDK projects and orchestrating project, stack, and resource actions through the TDK CLI.
-- `vscode-tdk-troubleshooting`: Diagnostic and remediation behavior for identifying common local development failures and presenting safe recovery actions.
-- `vscode-tdk-notifications`: Notification policy behavior for quiet background monitoring, actionable alerts, deduplication, and user-controlled notification preferences.
-
-### Modified Capabilities
-
-- None.
-
-## Impact
-
-- Adds a new VS Code extension repo/package at `/private/var/www/2025/ollamar1/tdk-vscode-extension`.
-- Uses the existing TDK CLI as the source of truth for project status, orchestration, health checks, and remediation commands.
-- The one-shot MVP MUST NOT require changing the TDK CLI. If structured CLI output is missing, the extension must use mocked adapters in tests and conservative raw-output parsing at runtime, then document follow-up CLI improvements.
-- Adds extension tests, command-runner tests, diagnostic classifier tests, and manual VS Code extension smoke testing.
-- Does not change the CLI command contract for existing users in the MVP.

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/specs/vscode-tdk-notifications/spec.md

@@ -1,48 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Notifications are quiet by default
-The extension SHALL avoid user-visible notifications for successful background polling and unchanged non-actionable states.
-
-#### Scenario: Background poll succeeds
-- **WHEN** a background status or health poll succeeds
-- **THEN** the extension updates internal state without showing a user-visible notification
-
-#### Scenario: Existing issue remains unchanged
-- **WHEN** a background poll observes an already-reported issue with the same fingerprint and severity
-- **THEN** the extension suppresses duplicate user-visible notifications
-
-### Requirement: Actionable failures notify the user
-The extension SHALL notify the user when a new or escalated issue requires attention.
-
-#### Scenario: New critical issue
-- **WHEN** a new critical TDK, Tilt, Docker, Bun, port, or configuration issue is detected
-- **THEN** the extension shows a notification with a concise summary and an action to open troubleshooting details
-
-#### Scenario: Issue severity escalates
-- **WHEN** a known issue changes to a higher severity
-- **THEN** the extension shows a new notification for the escalation
-
-### Requirement: Notifications are user configurable
-The extension SHALL provide settings that allow users to control notification categories and quiet behavior.
-
-#### Scenario: User disables stack failure notifications
-- **WHEN** stack failure notifications are disabled in settings
-- **THEN** the extension records stack failures in the troubleshooting view without showing user-visible stack failure notifications
-
-#### Scenario: User keeps critical notifications enabled
-- **WHEN** critical notifications are enabled
-- **THEN** the extension continues to notify for critical new or escalated issues
-
-### Requirement: Notification actions route to context
-The extension SHALL route notification actions to the relevant stack, resource, command output, or troubleshooting issue.
-
-#### Scenario: User opens issue from notification
-- **WHEN** the user selects the notification action to inspect an issue
-- **THEN** the extension opens the troubleshooting detail for the issue that triggered the notification
-
-### Requirement: Troubleshooter acts as notification history
-The extension SHALL retain actionable notification issues in the Troubleshooter view so users can revisit them after dismissing native VS Code notifications.
-
-#### Scenario: User dismisses notification
-- **WHEN** the user dismisses a native VS Code notification for an actionable issue
-- **THEN** the issue remains available in the Troubleshooter view until resolved or superseded

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/specs/vscode-tdk-orchestration/spec.md

@@ -1,63 +0,0 @@
-## ADDED Requirements
-
-### Requirement: VS Code extension detects TDK workspaces
-The extension SHALL detect whether the active VS Code workspace contains a TDK project before enabling orchestration actions.
-
-#### Scenario: TDK project detected
-- **WHEN** a workspace contains TDK project configuration or a valid TDK CLI project root
-- **THEN** the extension enables TDK views and commands for that workspace
-
-#### Scenario: Non-TDK workspace
-- **WHEN** a workspace does not contain a TDK project
-- **THEN** the extension shows a non-blocking empty state and keeps orchestration actions disabled
-
-### Requirement: Extension is delivered as a new package
-The extension SHALL be implemented as a new VS Code extension package at `/private/var/www/2025/ollamar1/tdk-vscode-extension`.
-
-#### Scenario: One-shot implementation starts
-- **WHEN** implementation begins
-- **THEN** the extension package is scaffolded outside `tdk-cli-core` at `/private/var/www/2025/ollamar1/tdk-vscode-extension`
-
-#### Scenario: Extension package is verified
-- **WHEN** the MVP is complete
-- **THEN** the package contains source code, package metadata, tests, documentation, and verification notes
-
-### Requirement: Extension runs orchestration through TDK CLI
-The extension SHALL execute project, stack, resource, doctor, status, up, and down actions through the TDK CLI instead of duplicating orchestration logic.
-
-#### Scenario: User starts a stack
-- **WHEN** the user starts a stack from VS Code
-- **THEN** the extension runs the corresponding TDK CLI stack lifecycle command in the workspace root and captures the command result
-
-#### Scenario: CLI command fails
-- **WHEN** a TDK CLI orchestration command exits with a non-zero status
-- **THEN** the extension preserves stdout, stderr, exit code, command, workspace, and duration for troubleshooting
-
-### Requirement: Extension exposes project, stack, and resource status
-The extension SHALL show project, stack, and resource status inside VS Code using TDK CLI status data.
-
-#### Scenario: Status refresh succeeds
-- **WHEN** the user refreshes TDK status
-- **THEN** the extension updates the visible project, stack, and resource state from the latest CLI result
-
-#### Scenario: Status refresh is cancelled
-- **WHEN** the user cancels an in-progress status refresh
-- **THEN** the extension stops the command and leaves the previous known status visible with a cancellation indication
-
-### Requirement: Extension provides required MVP surfaces
-The extension SHALL provide a TDK Explorer view, a Troubleshooter view, and a TDK output channel.
-
-#### Scenario: Extension activates in a TDK workspace
-- **WHEN** the extension activates in a detected TDK workspace
-- **THEN** the TDK Explorer, Troubleshooter view, and TDK output channel are available
-
-#### Scenario: Command output is produced
-- **WHEN** a TDK command runs through the extension
-- **THEN** the raw command output is appended to the TDK output channel
-
-### Requirement: MVP is VS Code only
-The IDE plugin SHALL support VS Code only for the MVP.
-
-#### Scenario: Non-VS Code IDE support requested
-- **WHEN** implementation scope is reviewed for the MVP
-- **THEN** JetBrains, Vim, browser IDE, and standalone Electron support are excluded from required delivery

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/specs/vscode-tdk-troubleshooting/spec.md

@@ -1,56 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Troubleshooter classifies common TDK failures
-The extension SHALL classify common local development failures using deterministic diagnostic rules based on CLI results, environment checks, and captured command evidence.
-
-#### Scenario: Missing prerequisite
-- **WHEN** Docker, Tilt, Bun, or the TDK CLI is missing or unavailable
-- **THEN** the troubleshooter identifies the missing prerequisite and presents the evidence that caused the classification
-
-#### Scenario: Port conflict
-- **WHEN** a TDK command or doctor result indicates that a required port is occupied
-- **THEN** the troubleshooter identifies the affected port and resource when that information is available
-
-#### Scenario: Invalid project configuration
-- **WHEN** TDK project defaults, tech stack config, Tiltfile, or service manifests are missing or invalid
-- **THEN** the troubleshooter identifies the invalid configuration area and links to the relevant file or command output when available
-
-#### Scenario: Tilt startup failure
-- **WHEN** a TDK lifecycle command reports a Tilt startup failure
-- **THEN** the troubleshooter identifies the failure as Tilt-related and preserves the relevant command output as evidence
-
-### Requirement: Troubleshooter presents likely cause and next action
-The extension SHALL show likely cause, confidence, evidence, and recommended next action for each classified issue.
-
-#### Scenario: Classified issue displayed
-- **WHEN** the troubleshooter opens a classified issue
-- **THEN** the issue detail includes severity, likely cause, confidence, evidence, and at least one next action
-
-#### Scenario: Unknown issue displayed
-- **WHEN** the troubleshooter cannot classify a failure
-- **THEN** the issue detail shows the raw command evidence and recommends a safe next diagnostic step
-
-### Requirement: Repair actions require explicit confirmation
-The extension SHALL require explicit user confirmation before running any repair action that changes files, starts or stops services, prunes resources, or modifies local environment state.
-
-#### Scenario: User selects state-changing repair
-- **WHEN** the user selects a repair action that changes local state
-- **THEN** the extension displays the exact command or operation and waits for confirmation before execution
-
-#### Scenario: User declines repair
-- **WHEN** the user declines a repair confirmation
-- **THEN** the extension does not run the repair and keeps the troubleshooting issue available
-
-### Requirement: Troubleshooter preserves diagnostic context
-The extension SHALL retain recent diagnostic context for failed commands so users can review evidence without rerunning the command immediately.
-
-#### Scenario: Failed orchestration command
-- **WHEN** an orchestration command fails
-- **THEN** the troubleshooter records the command metadata, raw output, parsed issue fingerprints, and timestamp
-
-### Requirement: CLI contract gaps are documented
-The extension SHALL document any missing or unstable TDK CLI output contract encountered during implementation instead of requiring CLI changes for the MVP.
-
-#### Scenario: CLI output cannot be parsed robustly
-- **WHEN** an adapter cannot reliably parse a TDK CLI command output
-- **THEN** the extension keeps raw output available and records the missing structured-output need in CLI contract gap documentation

package/openspec/changes/add-vscode-tdk-troubleshooter-plugin/tasks.md

@@ -1,61 +0,0 @@
-## 1. Scope Review and Repository Setup
-
-- [x] 1.1 Create `/private/var/www/2025/ollamar1/tdk-vscode-extension` as the new VS Code-only extension package location.
-- [x] 1.2 Add `docs/spec-critique.md` documenting MVP creep risks, unsafe repair risks, missing CLI contract risks, and how this implementation constrains each one.
-- [x] 1.3 Scaffold a TypeScript VS Code extension package with activation, command registration, test harness, lint/typecheck scripts, packaging metadata, and README.
-- [x] 1.4 Add extension configuration settings for TDK CLI path, polling behavior, notification categories, and safe repair confirmation behavior.
-- [x] 1.5 Add a verification checklist document that maps each spec requirement to implementation and test evidence.
-
-## 2. TDK CLI Integration Layer
-
-- [x] 2.1 Implement a command runner that captures command, cwd, stdout, stderr, exit code, duration, cancellation, and timestamp.
-- [x] 2.2 Implement TDK CLI discovery with support for configured binary path, workspace-local binary, and PATH fallback.
-- [x] 2.3 Implement workspace detection for TDK project roots and disabled empty-state behavior for non-TDK workspaces.
-- [x] 2.4 Implement typed adapters for `tdk doctor`, `tdk status`, `tdk stacks`, `tdk resources`, `tdk up`, and `tdk down`.
-- [x] 2.5 Add conservative raw-output parsing for adapters where structured JSON is unavailable.
-- [x] 2.6 Document missing structured-output needs in `docs/cli-contract-gaps.md` without modifying the TDK CLI.
-
-## 3. VS Code Orchestration UI
-
-- [x] 3.1 Add a TDK Explorer tree view for detected project, stacks, resources, and last known status.
-- [x] 3.2 Add commands for refresh status, run doctor, start stack/resource, stop stack/resource, and stop all services.
-- [x] 3.3 Add cancellation support for long-running refresh/doctor/orchestration commands.
-- [x] 3.4 Add a TDK output channel and append every executed command plus raw stdout/stderr.
-- [x] 3.5 Preserve raw command output and surface it from the relevant project, stack, resource, or command result.
-
-## 4. Troubleshooter
-
-- [x] 4.1 Define diagnostic issue types, severity levels, confidence levels, fingerprints, evidence records, and recommended next-action models.
-- [x] 4.2 Implement deterministic classifiers for missing TDK CLI, unsupported CLI version, non-TDK workspace, Docker unavailable, Tilt unavailable, Bun unavailable, occupied ports, missing/invalid master config, invalid service manifest, failed health endpoint, duplicate daemon, and Tilt startup failure.
-- [x] 4.3 Add a Troubleshooter view that shows issue list, severity, likely cause, confidence, evidence, raw output, and next actions.
-- [x] 4.4 Implement safe repair actions with explicit confirmation and exact command/operation preview for any state-changing action.
-- [x] 4.5 Ensure unknown failures retain raw command evidence and recommend a safe diagnostic next step.
-- [x] 4.6 Keep actionable issues available in the Troubleshooter view after native VS Code notifications are dismissed.
-
-## 5. Notification Management
-
-- [x] 5.1 Implement quiet-by-default background polling with no notifications for successful checks or unchanged non-actionable states.
-- [x] 5.2 Implement notification deduplication by issue fingerprint, workspace, resource, severity, and state transition.
-- [x] 5.3 Implement notifications for new critical issues, escalations, and completed user-triggered repair actions.
-- [x] 5.4 Route notification actions to the relevant troubleshooting detail, command output, stack, or resource.
-- [x] 5.5 Honor user settings for notification categories and quiet behavior.
-- [x] 5.6 Add tests proving dismissed native notifications do not remove issues from Troubleshooter history.
-
-## 6. Tests and Manual Validation
-
-- [x] 6.1 Add unit tests for command runner success, failure, cancellation, and output capture.
-- [x] 6.2 Add unit tests for TDK workspace detection and CLI discovery fallbacks.
-- [x] 6.3 Add unit tests for every deterministic diagnostic classifier and unknown-failure fallback.
-- [x] 6.4 Add tests for notification deduplication, escalation, and category suppression.
-- [x] 6.5 Add VS Code extension integration tests for activation, command registration, disabled non-TDK workspace state, and at least one orchestration command using a mocked CLI.
-- [x] 6.6 Add mocked CLI fixtures for success, failure, missing prerequisites, port conflict, invalid config, Tilt startup failure, and unknown failure.
-- [x] 6.7 Run lint, typecheck, unit tests, and VS Code extension tests.
-- [x] 6.8 Package or dry-run package the extension to prove the MVP can be installed locally.
-
-## 7. Documentation and Final Review
-
-- [x] 7.1 Document MVP usage, settings, supported commands, troubleshooting behavior, notification policy, and safe repair guarantees.
-- [x] 7.2 Document known limitations and follow-up candidates such as richer Tilt links, marketplace publishing, and optional AI-assisted troubleshooting.
-- [x] 7.3 Complete the verification checklist mapping every scenario in the three spec files to source code and test evidence.
-- [x] 7.4 Perform a final critical review of the specs and implementation for overreach, missed failure modes, notification noise, unsafe repair actions, and any gap that blocks one-shot MVP acceptance.
-- [x] 7.5 Record final commands run and results in the verification notes.

package/openspec/changes/archive/2026-04-28-rename-domain-to-stack-service-to-resource/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-27

package/openspec/changes/archive/2026-04-28-rename-domain-to-stack-service-to-resource/design.md

@@ -1,114 +0,0 @@
-## Context
-
-The codebase currently has terminology inconsistencies that have evolved over time:
-
-1. **"domain" vs "stack"**: The manifest schema originally used `domain` to group related services, but this has been migrated to `stack`. Currently, code uses fallback patterns like `manifest.get('stack') or manifest.get('domain')` to support both, creating confusion about which is canonical.
-
-2. **"service" vs "resource"**: The architecture has shifted from thinking in terms of "services" (business-oriented) to "resources" (deployment-oriented Tilt resources). Function names like `get_app_resources()` exist alongside variable names like `svc` and `service`, and docstrings refer to "services" while the code handles "resources".
-
-3. **Cache keys**: The discovery cache uses `domain_configs` which doesn't align with the `stack` terminology.
-
-4. **Autogenerated files**: Files like `product_autogenerated_domains_index.star` use old terminology.
-
-These inconsistencies make the codebase harder to understand, especially for new developers. Standardizing on "stack" (for logical grouping) and "resource" (for deployable units) will provide clarity.
-
-## Goals / Non-Goals
-
-**Goals:**
-- Replace all `domain` manifest field access with `stack` (remove fallbacks)
-- Rename `domain_configs` cache key to `stack_configs`
-- Update all docstrings and comments from "service" to "resource"
-- Rename variables from `svc`, `service` to `resource`
-- Rename functions like `_render_product_domains_index()` to `_render_product_stacks_index()`
-- Update autogenerated file naming from `domains` to `stacks`
-- Ensure no functional changes - purely terminology refactoring
-
-**Non-Goals:**
-- Changing manifest file structure (the JSON schema)
-- Changing the actual behavior of any function
-- Adding new features or capabilities
-- Removing support for legacy manifest formats in the loader/parser
-- Renaming the `app_resources` cache key (widely used, high risk)
-
-## Decisions
-
-### Decision 1: Keep `app_resources` Cache Key
-**Rationale**: The `app_resources` key is used extensively across the codebase (50+ references). Changing it would touch too many files and create high risk of merge conflicts. The term "app resources" is acceptable since it describes the collection of resources for an app.
-
-**Alternatives considered**:
-- Rename to `resources` - Rejected due to high touchpoint count and risk
-- Keep as-is - Accepted as "app resources" is descriptive enough
-
-### Decision 2: Remove `domain` Fallback Patterns
-**Rationale**: Patterns like `manifest.get('stack') or manifest.get('domain')` exist to support legacy manifests. However, all current manifests should have migrated to `stack`. Removing the fallback simplifies code and establishes `stack` as the canonical field.
-
-**Migration approach**:
-```starlark
-# Before:
-stack = manifest.get('stack') or manifest.get('domain') or extract_stack_from_path(path)
-
-# After:
-stack = manifest.get('stack', extract_stack_from_path(path))
-```
-
-### Decision 3: Update Variable Names Incrementally
-**Rationale**: Variables like `svc`, `service` should become `resource`. However, in loops where context is clear (e.g., `for svc in resources`), shorter names are acceptable. Focus on function parameters and docstrings first.
-
-**Priority order**:
-1. Function parameter names
-2. Docstrings and comments
-3. Variable names in outer scope
-4. Loop variables (lower priority)
-
-### Decision 4: File Renaming for Autogenerated Files
-**Rationale**: Autogenerated files like `product_autogenerated_domains_index.star` should be renamed to use `stacks`. This requires updating both the file generation code and any `load()` statements that reference these files.
-
-## Risks / Trade-offs
-
-**Risk**: Breaking external code that reads `domain` from manifests
-- **Mitigation**: This is a **BREAKING** change as noted. External code must migrate to `stack` field.
-
-**Risk**: Inadvertent functional changes during bulk renaming
-- **Mitigation**: Each task will be focused on a specific file or small group. Tests must pass after each batch.
-
-**Risk**: Merge conflicts with ongoing development
-- **Mitigation**: Tasks are organized by directory to minimize conflict surface area. Complete quickly.
-
-**Risk**: Missing some instances of old terminology
-- **Mitigation**: Final verification task will grep for remaining `domain`, `svc`, `service` patterns.
-
-**Risk**: Variable name collisions after renaming
-- **Mitigation**: Use `resource` not `res` (too short). In nested contexts, use descriptive names like `app_resource`.
-
-## Migration Plan
-
-1. **Phase 1: Discovery System** (Tasks 1-40)
-   - Update `/discovery/` directory files
-   - Rename `domain_configs` to `stack_configs`
-   - Update manifest access patterns
-   - Update docstrings
-
-2. **Phase 2: Engine Topologies Tilt** (Tasks 41-100)
-   - Update deprecated system files
-   - Update generator files
-   - Update resource orchestration
-
-3. **Phase 3: Engine Topologies Platform** (Tasks 101-130)
-   - Update platform-level files
-   - Update Docker, networking, compose files
-
-4. **Phase 4: Autogenerated File Naming** (Tasks 131-140)
-   - Rename autogenerated file references
-   - Update file generation code
-
-5. **Phase 5: Verification** (Tasks 141-150)
-   - Run full test suite
-   - Grep for remaining `domain` references
-   - Grep for remaining `service` vs `resource` inconsistencies
-   - Verify no `manifest.get('domain')` patterns remain
-
-## Open Questions
-
-- Should we keep `app_resources` as-is or rename to `resources`? (Decision: keep as-is for now)
-- Should we update function names like `get_app_resources()`? (Decision: lower priority, focus on internals first)
-- How to handle `svc` in tight loops where context is clear? (Decision: focus on function params and docstrings first)

package/openspec/changes/archive/2026-04-28-rename-domain-to-stack-service-to-resource/proposal.md

@@ -1,32 +0,0 @@
-## Why
-
-The codebase currently uses inconsistent terminology: "domain" vs "stack" and "service" vs "resource" are used interchangeably, causing confusion. The manifest schema has migrated from `domain` to `stack` as the preferred field, and the architecture has shifted from "services" to "resources" as the core abstraction. Standardizing on "stack" (for grouping/organizing) and "resource" (for individual deployable units) will clarify the mental model and reduce cognitive overhead for developers working across 174+ .star files.
-
-## What Changes
-
-- **BREAKING** Rename all `domain` references to `stack` in manifest field access patterns (`manifest.get('domain')` → `manifest.get('stack')`)
-- **BREAKING** Rename `domain_configs` cache key to `stack_configs`
-- **BREAKING** Rename `_render_product_domains_index()` function to `_render_product_stacks_index()`
-- **BREAKING** Update all function docstrings and comments from "service" to "resource" terminology
-- **BREAKING** Rename variables like `svc` to `resource`, `service` to `resource` throughout
-- Remove fallback patterns like `manifest.get('stack') or manifest.get('domain')` and use only `stack`
-- Update autogenerated file names from `domains` to `stacks`
-
-## Capabilities
-
-### New Capabilities
-- `stack-terminology-standard`: Standardize all grouping/organization terminology to "stack"
-- `resource-terminology-standard`: Standardize all deployable unit terminology to "resource"
-- `manifest-field-migration`: Remove deprecated `domain` field support from manifest access patterns
-
-### Modified Capabilities
-<!-- No existing spec requirements are changing - this is terminology refactoring -->
-
-## Impact
-
-- **Affected Files**: 50+ .star files across `/discovery/`, `/engine/topologies/tilt/`, `/engine/topologies/platform/`
-- **Function Count**: 200+ function names, variables, and docstrings will be updated
-- **Dependencies**: Any external code accessing `domain` field in manifests will need to use `stack`
-- **Breaking Changes**: **BREAKING** - Manifest field access changes, function renames, cache key renames
-- **Risk Level**: High - extensive terminology changes across many files
-- **Testing Required**: Full test suite to verify no functional regressions

package/openspec/changes/archive/2026-04-28-rename-domain-to-stack-service-to-resource/specs/manifest-field-migration/spec.md

@@ -1,20 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Manifest field migration from domain to stack
-All manifest field access patterns SHALL remove fallback support for the deprecated `domain` field.
-
-#### Scenario: No domain field fallback
-- **WHEN** code retrieves the stack field from a manifest
-- **THEN** it SHALL NOT use fallback patterns like `manifest.get('stack') or manifest.get('domain')`
-
-#### Scenario: Stack field with default only
-- **WHEN** a default value is needed for the stack field
-- **THEN** code SHALL use `manifest.get('stack', default_value)` and NOT check for domain
-
-#### Scenario: Domain field references removed
-- **WHEN** searching the codebase for domain field access
-- **THEN** no `manifest.get('domain')` patterns SHALL exist except in legacy parser code
-
-#### Scenario: Filtering uses stack field only
-- **WHEN** filtering manifests by logical group
-- **THEN** code SHALL filter by `stack` field only and NOT check `domain` as fallback

package/openspec/changes/archive/2026-04-28-rename-domain-to-stack-service-to-resource/specs/resource-terminology-standard/spec.md

@@ -1,20 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Resource terminology standardization
-All references to deployable units SHALL use the term "resource" instead of "service".
-
-#### Scenario: Function parameters use resource terminology
-- **WHEN** a function accepts a deployable unit as a parameter
-- **THEN** the parameter name SHALL be `resource` or `resource_dict` and NOT `service` or `svc`
-
-#### Scenario: Docstrings use resource terminology
-- **WHEN** a function docstring describes a deployable unit
-- **THEN** it SHALL use the term "resource" and NOT "service"
-
-#### Scenario: Variable names use resource terminology
-- **WHEN** a variable holds a deployable unit
-- **THEN** the variable name SHALL be `resource` and NOT `svc` or `service`
-
-#### Scenario: Comments use resource terminology
-- **WHEN** code comments describe deployable units
-- **THEN** they SHALL use the term "resource" and NOT "service"

package/openspec/changes/archive/2026-04-28-rename-domain-to-stack-service-to-resource/specs/stack-terminology-standard/spec.md

@@ -1,20 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Stack terminology standardization
-All references to logical grouping of resources SHALL use the term "stack" instead of "domain".
-
-#### Scenario: Manifest field access uses stack
-- **WHEN** code accesses the grouping field from a manifest
-- **THEN** it SHALL use `manifest.get('stack')` and NOT `manifest.get('domain')`
-
-#### Scenario: Cache keys use stack terminology
-- **WHEN** the discovery cache stores configuration for logical groups
-- **THEN** the cache key SHALL be named `stack_configs` and NOT `domain_configs`
-
-#### Scenario: Autogenerated files use stack naming
-- **WHEN** autogenerated index files are created for logical groups
-- **THEN** the filenames SHALL contain `stacks` and NOT `domains`
-
-#### Scenario: Function names use stack terminology
-- **WHEN** a function generates an index of logical groups
-- **THEN** the function name SHALL include `stacks` and NOT `domains`