hammerkit 1.5.0 → 1.6.0-alpha.1

package/specs/cli/up/spec.md

@@ -0,0 +1,80 @@
+# Feature Specification: CLI: up
+
+**Feature Branch**: `001-current-state-specs`
+
+**Created**: 2026-05-30
+
+**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
+
+**Input**: Existing behavior documented in `docs/cli/up.md`
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Starting shared services for local development (Priority: P1)
+
+A developer needs a database running continuously while they iterate on several tasks. Instead of letting each task start and stop the database automatically, they run `hammerkit up` to start all services and keep them alive. When they are done for the day, they run `hammerkit down`.
+
+**Why this priority**: Persistent service management during development is the primary use case for the `up` command; it directly reduces the startup overhead between task runs.
+
+**Independent Test**: Given a build file with a service (e.g., `postgres`), run `hammerkit up` and verify the service container is running and remains running until the process is interrupted or `hammerkit down` is called.
+
+**Acceptance Scenarios**:
+
+1. **Given** a build file with one or more services, **When** the user runs `hammerkit up`, **Then** all services start and the process blocks until the user sends an interrupt signal (Ctrl+C or equivalent).
+
+2. **Given** a build file with one or more services, **When** the user runs `hammerkit up --daemon`, **Then** all services start in the background and the command returns immediately with exit code 0.
+
+3. **Given** services started with `hammerkit up --daemon`, **When** the user subsequently runs `hammerkit down`, **Then** those services are stopped.
+
+4. **Given** a build file with multiple services and only some bearing a specific label, **When** the user runs `hammerkit up -f <label>`, **Then** only the services matching the label are started.
+
+5. **Given** a build file with multiple services and some bearing an excluded label, **When** the user runs `hammerkit up -e <label>`, **Then** services matching the excluded label are not started.
+
+### User Story 2 - Starting services in a named environment (Priority: P2)
+
+A developer wants to start services inside a Kubernetes cluster configured under `environments:` in their build file. They pass `--env <name>` to target that environment instead of the local Docker runtime.
+
+**Why this priority**: Multi-environment support is an important power-user scenario but not required for local Docker-based development.
+
+**Independent Test**: Given a build file with a named Kubernetes environment, run `hammerkit up --env <name>` and verify that service start commands target the configured environment.
+
+**Acceptance Scenarios**:
+
+1. **Given** a named environment declared in the build file, **When** the user runs `hammerkit up --env <name>`, **Then** services are started within that environment's runtime.
+
+### Edge Cases
+
+- Running `hammerkit up` when no services are defined in the build file should exit cleanly (code 0) with an informational message.
+- Running `hammerkit up --daemon` multiple times for already-running services should either be idempotent or report that services are already running.
+- Interrupt signal during foreground `up` must cleanly stop the started services before exiting.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST start all services defined in the build file when `hammerkit up` is run without filter options.
+- **FR-002**: System MUST keep services running and block the terminal until interrupted, unless `--daemon` is supplied.
+- **FR-003**: System MUST start services in the background and return immediately when `--daemon` is supplied.
+- **FR-004**: System MUST support label-based inclusion filtering via `-f / --filter <key=value>` to start only matching services.
+- **FR-005**: System MUST support label-based exclusion filtering via `-e / --exclude <key=value>` to skip matching services.
+- **FR-006**: System MUST support an `--env <name>` option to start services in a configured named environment.
+- **FR-007**: System MUST support `-c / --concurrency <number>`, `-w / --watch`, `--cache <method>`, and `-l / --log <mode>` options (consistent with the `run` command option surface).
+
+### Key Entities
+
+- **Service**: A long-running container (e.g., a database) declared in the build file under `services:`, started and kept running by `up`.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: After `hammerkit up` (foreground), the service container is reachable on its declared port while the process is running.
+- **SC-002**: After `hammerkit up --daemon`, the command exits with code 0 and the service container is reachable on its declared port.
+- **SC-003**: With `-f <label>`, only services bearing that label are started; other services remain stopped.
+- **SC-004**: Services started with `hammerkit up` are stopped when the foreground process receives an interrupt signal.
+
+## Assumptions
+
+- Services that are already running (e.g., started by a prior `up` invocation) are handled gracefully; exact behavior (skip, restart, error) is an implementation detail not specified in the docs.
+- The `--watch` and `--cache` flags carry over from the `run` command option surface and apply to any tasks that services might trigger; their exact effect on pure-service `up` runs is not specified in the docs and assumed to be a no-op for services themselves.
+- `--env` targets named environments declared under the `environments:` key in the build file (informed by the cross-reference to the Kubernetes doc).

package/specs/cli/validate/spec.md

@@ -0,0 +1,70 @@
+# Feature Specification: CLI: validate
+
+**Feature Branch**: `001-current-state-specs`
+
+**Created**: 2026-05-30
+
+**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
+
+**Input**: Existing behavior documented in `docs/cli/validate.md`
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Catch build-file errors before running tasks (Priority: P1)
+
+A developer edits `.hammerkit.yaml` and wants to verify the configuration is correct before triggering a potentially long-running build. They run `hammerkit validate`, which checks the build file for invalid configurations or missing information and reports any problems immediately.
+
+**Why this priority**: Early error detection prevents wasted time on builds that would fail partway through due to a misconfigured build file.
+
+**Independent Test**: Introduce a deliberate misconfiguration in a build file (e.g., a task referencing a non-existent dependency). Run `hammerkit validate`. Confirm the command exits with a non-zero code and reports the error. Then fix the file and confirm `hammerkit validate` exits successfully.
+
+**Acceptance Scenarios**:
+
+1. **Given** a build file with a valid configuration, **When** `hammerkit validate` is run, **Then** the command exits with a success code and reports no errors.
+
+2. **Given** a build file with an invalid configuration (e.g., missing required fields, unknown references), **When** `hammerkit validate` is run, **Then** the command exits with a non-zero code and reports a clear description of each problem found.
+
+3. **Given** a build file with missing required information, **When** `hammerkit validate` is run, **Then** the specific missing information is identified in the output.
+
+### User Story 2 - Use validate as a CI linting step (Priority: P2)
+
+A CI pipeline operator adds `hammerkit validate` as an early linting job alongside other linters so that build-file errors are caught on every pull request before any build or test jobs run.
+
+**Why this priority**: The docs explicitly recommend this usage pattern; catching errors in CI prevents broken build configurations from reaching the main branch.
+
+**Independent Test**: Add `hammerkit validate` to a CI job. Introduce a build-file error on a branch. Confirm the CI job fails. Fix the error and confirm the CI job passes.
+
+**Acceptance Scenarios**:
+
+1. **Given** `hammerkit validate` is included as a CI job step, **When** a pull request introduces an invalid build file, **Then** the CI job fails and the error is visible in the CI output before any build or test jobs run.
+
+2. **Given** a valid build file, **When** `hammerkit validate` runs in CI, **Then** the job passes and downstream jobs are not blocked.
+
+### Edge Cases
+
+- Running `hammerkit validate` when no build file exists should exit with a non-zero code and report a clear error about the missing file.
+- A build file that is syntactically valid YAML but contains semantically invalid hammerkit configuration (e.g., referencing an undefined task as a dependency) should be caught by validate.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST parse and validate the build file when `hammerkit validate` is run.
+- **FR-002**: System MUST exit with a success code when the build file contains no invalid configurations or missing required information.
+- **FR-003**: System MUST exit with a non-zero code and report all detected errors when the build file contains invalid configurations or missing required information.
+- **FR-004**: Error output MUST describe each problem clearly enough for a developer to identify and fix it without additional tooling.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: `hammerkit validate` exits with code 0 for every valid build file accepted by `hammerkit run`.
+- **SC-002**: `hammerkit validate` exits with a non-zero code for every build file that would cause `hammerkit run` to fail due to a configuration error.
+- **SC-003**: Each error message produced by `hammerkit validate` identifies the location or nature of the problem sufficiently for a developer to correct it.
+
+## Assumptions
+
+- `hammerkit validate` validates the build file in the current working directory (defaulting to `.hammerkit.yaml`); alternate file paths are not documented and are assumed unsupported by this command.
+- The command performs static analysis only — it does not execute tasks, pull images, or make network calls to verify external resources.
+- No `--filter`/`--exclude` options are documented for `validate`; the command always validates the entire build file.
+- "Invalid configurations" includes but may not be limited to: undefined task/service references, missing required fields, and type mismatches in the schema.

package/specs/labels/spec.md

@@ -0,0 +1,91 @@
+# Feature Specification: Labels: Overview
+
+**Feature Branch**: `001-current-state-specs`
+
+**Created**: 2026-05-30
+
+**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
+
+**Input**: Existing behavior documented in `docs/labels/README.md`
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Filtering tasks to run only a matching subset (Priority: P1)
+
+A developer works in a monorepo with tasks for multiple projects. They tag each task with a `project` label and run `hammerkit task -f project=a` to execute only the tasks (and their dependencies) that carry that label.
+
+**Why this priority**: Label-based task filtering is the primary value proposition of labels — enabling targeted runs in complex build files without manually listing task names.
+
+**Independent Test**: Declare tasks `build-a` and `build-b` with labels `project: a` and `project: b` respectively. Run `hammerkit -f project=a` and confirm only tasks with `project=a` (and their deps) are executed, not `build-b`.
+
+**Acceptance Scenarios**:
+
+1. **Given** tasks with different `project` label values, **When** `hammerkit -f project=a` is executed, **Then** only tasks whose `project` label equals `a` are included in the run.
+
+2. **Given** a task with label `project: a` has a dependency task without any labels, **When** `hammerkit -f project=a` is run, **Then** the unlabelled dependency is still executed as part of the filtered run.
+
+### User Story 2 - Excluding tasks by label (Priority: P1)
+
+A CI pipeline runs on two separate runners — one macOS, one Linux. The macOS runner should skip all non-iOS tasks. The operator uses `hammerkit -e platform=ios` on the Linux runner to exclude all tasks labelled `platform: ios`.
+
+**Why this priority**: Exclusion (`-e`) is equally important to inclusion (`-f`) for CI matrix setups and is documented side-by-side.
+
+**Independent Test**: Declare tasks with and without `platform: ios`. Run `hammerkit -e platform=ios` and confirm tasks labelled `platform: ios` are skipped while unlabelled tasks run.
+
+**Acceptance Scenarios**:
+
+1. **Given** a mix of tasks with and without `platform: ios`, **When** `hammerkit -e platform=ios` is run, **Then** tasks with `platform: ios` are excluded and all other tasks proceed normally.
+
+2. **Given** the macOS runner uses `hammerkit -f platform=ios`, **When** executed, **Then** only tasks labelled `platform: ios` run on that host.
+
+### User Story 3 - Grouping unrelated tasks under a common label for parallel or sequential execution (Priority: P2)
+
+A developer wants a single command to start both an API server and a frontend watcher that have no dependency between them. They assign both a `task: dev` label and run `hammerkit -f task=dev` to start them together.
+
+**Why this priority**: Grouping by purpose simplifies developer workflows and reduces the need to remember multiple task names.
+
+**Independent Test**: Declare two independent tasks with `task: dev`. Run `hammerkit -f task=dev` and verify both tasks are executed in the same run.
+
+**Acceptance Scenarios**:
+
+1. **Given** two independent tasks share `task: dev`, **When** `hammerkit -f task=dev` is executed, **Then** both tasks run in the same invocation.
+
+2. **Given** tasks labelled `task: release` are also present, **When** `hammerkit -f task=dev` is run, **Then** release tasks are not executed.
+
+### Edge Cases
+
+- A label is a key-value pair; both key and value must be specified in filter/exclusion flags (e.g. `-f project=a`, not `-f project`).
+- Labels can be defined at the task level or at the build-file level (build-file-level labels apply to all tasks in that file).
+- When using store/restore across CI hosts with label-filtered runs, the `store` and `restore` commands accept the same `-f`/`-e` label arguments (e.g. `hammerkit store -e platform=ios`).
+- A task with no labels is included in runs that use `-f` only if it is a dependency of a matching task; it is never excluded by `-e` (since it has no matching label).
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST support defining labels as key-value pairs on individual tasks.
+- **FR-002**: System MUST support defining labels at the build-file level, applying them to all tasks in that file.
+- **FR-003**: System MUST provide a `-f <key>=<value>` CLI flag that restricts the run to tasks whose labels include the specified key-value pair (and their dependencies).
+- **FR-004**: System MUST provide a `-e <key>=<value>` CLI flag that excludes tasks whose labels include the specified key-value pair from the run.
+- **FR-005**: System MUST apply `-f` and `-e` label arguments to `store` and `restore` CLI commands in addition to task execution commands.
+- **FR-006**: System MUST still execute unlabelled dependency tasks required by label-matched tasks when `-f` filtering is active.
+
+### Key Entities
+
+- **Label**: A key-value pair attached to a task or build file. Both key and value are strings.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Running with `-f <key>=<value>` results in only tasks carrying that label (and their transitive dependencies) being executed, confirmed by execution logs.
+- **SC-002**: Running with `-e <key>=<value>` results in no task carrying that label being executed, confirmed by execution logs.
+- **SC-003**: Build files with overlapping task graphs (monorepo scenario) can be filtered to isolated subsets using a single label flag without editing the build file.
+- **SC-004**: `hammerkit store -e platform=ios` and `hammerkit store -f platform=ios` honour the same label filtering logic as task execution.
+
+## Assumptions
+
+- Labels are case-sensitive for both key and value comparisons.
+- Multiple `-f` or `-e` flags in a single invocation are assumed to be AND-combined (all specified labels must match), though the docs do not explicitly state this; noted as an assumption.
+- Build-file-level labels are inherited by all tasks in the file but can be overridden at the task level; the docs mention both scopes without describing conflict resolution, so this is assumed additive (file labels + task labels merge).
+- Labels are metadata only and have no effect on task execution order beyond determining which tasks are included or excluded.

package/specs/service/container/spec.md

@@ -0,0 +1,120 @@
+# Feature Specification: Service: Container
+
+**Feature Branch**: `001-current-state-specs`
+
+**Created**: 2026-05-30
+
+**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
+
+**Input**: Existing behavior documented in `docs/service/container.md`
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Declaring a container service with a healthcheck (Priority: P1)
+
+A developer needs a postgres database that is fully ready before any dependent task starts. They declare a container service with an `image`, optional environment variables, and a `healthcheck` command. Hammerkit starts the container and repeatedly executes the healthcheck inside it; when the command exits 0, dependent tasks are unblocked.
+
+**Why this priority**: The healthcheck is the central correctness guarantee for container services — without it tasks may fail due to a not-yet-ready service.
+
+**Independent Test**: Declare a postgres service with `healthcheck.cmd: "pg_isready -U postgres"`. Run a task that needs it and confirm the task only begins after `pg_isready` returns 0.
+
+**Acceptance Scenarios**:
+
+1. **Given** a container service with a `healthcheck` configured, **When** a task that needs the service is triggered, **Then** hammerkit does not start the task until the healthcheck command exits with code 0 inside the service container.
+
+2. **Given** a container service with no `healthcheck`, **When** a task that needs it is triggered, **Then** hammerkit starts the task as soon as the container is running (without waiting for application readiness).
+
+### User Story 2 - Exposing service ports to the host for debugging (Priority: P2)
+
+A developer wants to connect a local SQL client to a running postgres service for inspection. They declare a `ports` mapping on the service so the container port is published to the host machine.
+
+**Why this priority**: Port exposure is optional for task connectivity but commonly needed during development for direct access.
+
+**Independent Test**: Declare a postgres service with `ports: [5432:5432]`. Start the service and verify that a connection to `localhost:5432` from the host succeeds.
+
+**Acceptance Scenarios**:
+
+1. **Given** a service declares `ports: - 5432:5432`, **When** the service is running, **Then** port 5432 on the host machine is forwarded to the service container.
+
+2. **Given** no `ports` are declared on a service, **When** a container task that needs it runs, **Then** the task can still reach the service on all its container ports via the container network without any published ports.
+
+### User Story 3 - Persisting service data across restarts with volumes (Priority: P2)
+
+A developer wants database data to survive service restarts. They add a `volumes` entry mapping a named volume to the data directory inside the container.
+
+**Why this priority**: Without volumes, container services lose all state on every stop/start cycle, which breaks local development workflows.
+
+**Independent Test**: Declare a postgres service with a volume, seed it with data, stop and restart the service, and verify the data is still present.
+
+**Acceptance Scenarios**:
+
+1. **Given** a service declares a named volume (e.g. `postgres-db:/var/lib/postgresql/data`), **When** the service is stopped and restarted, **Then** data written during the first run is still available after restart.
+
+### User Story 4 - Mounting local config files into a service container (Priority: P3)
+
+A developer needs to supply a custom postgres configuration file. They declare a `mounts` entry to bind-mount the local file into the container at the expected path.
+
+**Why this priority**: Mounts are an advanced configuration option; most services do not require them.
+
+**Independent Test**: Declare a service with a mount pointing to a local config file. Start the service and verify the file is accessible at the mounted path inside the container.
+
+**Acceptance Scenarios**:
+
+1. **Given** a service declares `mounts: - "./postgres.conf:/etc/postgresql/postgresql.conf"`, **When** the service container starts, **Then** the file at `./postgres.conf` on the host is readable at `/etc/postgresql/postgresql.conf` inside the container.
+
+### User Story 5 - Exporting and importing service volume data (Priority: P3)
+
+A developer seeds a local database from a known-good snapshot using `hammerkit store` / `hammerkit restore` to export and import the service's volume data.
+
+**Why this priority**: Store/restore for services is a power feature enabling reproducible environments and data sharing between teammates.
+
+**Independent Test**: Run a service, write data, run `hammerkit store`, wipe the volume, run `hammerkit restore`, verify data is back.
+
+**Acceptance Scenarios**:
+
+1. **Given** a running service with volume data, **When** `hammerkit store` is executed for that service, **Then** the volume data is exported to a transferable archive.
+
+2. **Given** an exported archive, **When** `hammerkit restore` is executed, **Then** the service volume is populated with the archived data.
+
+### Edge Cases
+
+- A service without a healthcheck may start a dependent task before the service application is ready to accept connections.
+- Mounts of large or frequently changing directories on macOS and Windows incur significant CPU overhead due to filesystem sync; volumes are preferred for data.
+- A service is stopped automatically when no further tasks in the current run require it (unless kept alive via `hammerkit up`).
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST start container services using the specified `image`.
+- **FR-002**: System MUST pass declared `envs` as environment variables into the service container.
+- **FR-003**: System MUST publish declared `ports` mappings from the service container to the host machine.
+- **FR-004**: System MUST execute the `healthcheck.cmd` inside the service container and only unblock dependent tasks once it exits with code 0.
+- **FR-005**: System MUST mount declared `volumes` (named volumes and bind paths) into the service container to persist data across restarts.
+- **FR-006**: System MUST bind-mount declared `mounts` (host path to container path) into the service container.
+- **FR-007**: System MUST make all container ports of a service reachable from other container tasks in the same network, regardless of whether `ports` are published to the host.
+- **FR-008**: System MUST support store/restore operations on service volumes via the `hammerkit store` and `hammerkit restore` CLI commands.
+
+### Key Entities
+
+- **Container Service**: A service with an `image`, optional `envs`, `ports`, `healthcheck`, `volumes`, and `mounts`.
+- **Healthcheck**: Contains a `cmd` string executed inside the service container. A zero exit code signals readiness.
+- **Volume**: A named or path-based Docker volume entry mapping a volume identifier to a container path.
+- **Mount**: A bind-mount entry mapping a host file/directory path to a container path.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: A task dependent on a service with a healthcheck does not start until the healthcheck exits 0, verified by log timestamps.
+- **SC-002**: A declared port mapping results in a reachable port on the host machine while the service is running.
+- **SC-003**: Data written to a volume-backed service directory is present after the service container is stopped and restarted.
+- **SC-004**: A bind-mounted file is readable at its declared container path when the service container is inspected.
+- **SC-005**: `hammerkit store` produces a restorable artifact and `hammerkit restore` repopulates the volume to a matching state.
+
+## Assumptions
+
+- Container services run within the same Docker network as container tasks; no additional network configuration is needed for inter-container communication.
+- The `healthcheck.cmd` is a shell command string executed inside the service container (not on the host).
+- Services sharing volumes across multiple hammerkit projects run as a single container instance, not duplicated per project.
+- `ports` are not required for container tasks to reach the service — they are solely for host-side access.

package/specs/service/kubernetes/spec.md

@@ -0,0 +1,97 @@
+# Feature Specification: Service: Kubernetes
+
+**Feature Branch**: `001-current-state-specs`
+
+**Created**: 2026-05-30
+
+**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
+
+**Input**: Existing behavior documented in `docs/service/kubernetes.md`
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Forwarding a Kubernetes deployment port to a local task (Priority: P1)
+
+A developer wants to run a local task against a staging database that lives in a Kubernetes cluster. They declare an environment with the cluster context, declare a Kubernetes service with a `selector` pointing to the deployment and the ports to forward, then run their task with `--env staging`. Hammerkit establishes the port-forward and the task reaches the database on localhost.
+
+**Why this priority**: This is the primary use case of Kubernetes services — accessing remote cluster resources locally without leaving the hammerkit workflow.
+
+**Independent Test**: Declare a `prod` environment with a valid kubeconfig context and a service selecting a known deployment. Run `hammerkit <task> --env prod` and confirm the task can connect on the forwarded port.
+
+**Acceptance Scenarios**:
+
+1. **Given** an environment declares a Kubernetes `context` and a service declares a `selector` with `type: deployment` and a `name`, **When** a task needing the service is run with `--env <env>`, **Then** hammerkit forwards the specified ports from the matching deployment to localhost.
+
+2. **Given** an environment named `default` exists in the build file, **When** a task is run without `--env`, **Then** hammerkit uses the `default` environment automatically.
+
+3. **Given** the same service definition, **When** the task is run with `--env local` versus `--env prod`, **Then** the port-forward targets the cluster configured in the respective environment.
+
+### User Story 2 - Overriding the namespace or context per service (Priority: P2)
+
+A developer has a `prod` environment pointing to a GKE cluster with a default namespace of `databases`, but one service lives in the `orders` namespace. They add `namespace: orders` on that service to override only the namespace while inheriting everything else from the environment.
+
+**Why this priority**: Per-service overrides allow a single build file to target resources spread across multiple namespaces without duplicating environment definitions.
+
+**Independent Test**: Declare an environment with `namespace: databases` and a service that overrides `namespace: orders`. Verify the port-forward targets the `orders` namespace.
+
+**Acceptance Scenarios**:
+
+1. **Given** an environment declares `namespace: databases` and a service declares `namespace: orders`, **When** the service is activated, **Then** the port-forward targets the `orders` namespace, not `databases`.
+
+2. **Given** a service declares neither `namespace`, `context`, nor `kubeconfig`, **When** it is activated, **Then** it inherits all three from the selected environment.
+
+### User Story 3 - Connecting to different cloud providers (Priority: P3)
+
+A developer's team uses GKE for prod and EKS for staging. They configure two environments with the appropriate context names written by the cloud CLI tools. Services are declared once and are provider-agnostic.
+
+**Why this priority**: Multi-provider support broadens the tool's applicability but is a configuration concern, not a behavioral distinction.
+
+**Independent Test**: Declare two environments with provider-specific context names and run the same service-needing task against each; verify the correct cluster is targeted each time.
+
+**Acceptance Scenarios**:
+
+1. **Given** a GKE environment with context `gke_<project>_<location>_<cluster>`, **When** a task is run with that environment, **Then** hammerkit connects to the GKE cluster via the matching kubeconfig entry.
+
+2. **Given** an AKS environment with a dedicated `kubeconfig` file, **When** a task is run with that environment, **Then** hammerkit uses the specified kubeconfig file rather than the default `~/.kube/config`.
+
+### Edge Cases
+
+- If no matching deployment, service, or pod exists in the target cluster namespace, the port-forward fails and the task does not start.
+- If neither the service nor the environment specifies a `namespace`, hammerkit defaults to the `default` Kubernetes namespace.
+- The `kubectl` binary is not required; hammerkit performs port-forwarding directly through the Kubernetes client library.
+- A service can override `context` or `kubeconfig` individually while still inheriting the other fields from the environment.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST forward ports from a Kubernetes resource to localhost using the `selector` (type and name) and `ports` declared on the service.
+- **FR-002**: System MUST resolve the cluster connection (`context`, `kubeconfig`, `namespace`) from the environment selected via `--env`.
+- **FR-003**: System MUST use the environment named `default` when no `--env` flag is provided and such an environment exists.
+- **FR-004**: System MUST allow a service to override `namespace`, `context`, and/or `kubeconfig` independently, inheriting unoverridden fields from the environment.
+- **FR-005**: System MUST support `selector.type` values of `deployment`, `service`, and `pod`.
+- **FR-006**: System MUST establish port-forwarding without requiring the `kubectl` binary on the host.
+- **FR-007**: System MUST default to the environment's `kubeconfig`, falling back to `$HOME/.kube/config` when neither the service nor the environment specifies one.
+- **FR-008**: System MUST default to the environment's `namespace`, falling back to `default` when neither specifies one.
+
+### Key Entities
+
+- **Kubernetes Service**: A service entry with `selector` (resource `type` and `name`), `ports` (host:container mappings), and optional `namespace`, `context`, `kubeconfig` overrides.
+- **Environment**: A named block under `environments` containing a `kubernetes` sub-key with `context`, optional `kubeconfig`, and optional `namespace`.
+- **Selector**: Specifies the Kubernetes resource to forward from. Fields: `type` (deployment | service | pod) and `name`.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: A task that needs a Kubernetes service can connect to the forwarded port on localhost while the task runs, verified by a successful network call.
+- **SC-002**: Switching `--env` between two environments with different cluster contexts results in the port-forward targeting the correct cluster, confirmed by which database responds.
+- **SC-003**: A per-service `namespace` override causes the forward to target the overriding namespace, not the environment's default namespace.
+- **SC-004**: Port-forwarding succeeds on a machine that does not have `kubectl` installed.
+
+## Assumptions
+
+- Each port mapping in `ports` follows `hostPort:containerPort` notation; hammerkit binds `hostPort` on localhost and forwards to `containerPort` on the selected Kubernetes resource.
+- The `--env` flag is the only mechanism for selecting a Kubernetes environment at runtime; there is no interactive prompt.
+- Kubernetes services in hammerkit are for port-forwarding only — they do not schedule workloads on the cluster (see task/kubernetes.md for running tasks on a cluster).
+- A Kubernetes service without an explicit `image` field is distinguished from a container service by the presence of a `selector` field.

package/specs/service/spec.md

@@ -0,0 +1,105 @@
+# Feature Specification: Service: Overview
+
+**Feature Branch**: `001-current-state-specs`
+
+**Created**: 2026-05-30
+
+**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
+
+**Input**: Existing behavior documented in `docs/service/README.md`
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Running a dependency service alongside a container task (Priority: P1)
+
+A developer needs a database available before their application task starts. They declare a `postgres` service in the build file and add it to the task's `needs` list. When they run the task, hammerkit starts the service first (waiting for its healthcheck to pass if one is configured), then starts the task container — both share a container network so the task can reach the service by its name (e.g. `postgres:5432`).
+
+**Why this priority**: Services are the primary mechanism for wiring runtime dependencies to tasks; this is the core use case documented first.
+
+**Independent Test**: Create a build file with a postgres service and a container task that `needs` it. Run the task and confirm it connects to postgres using the service name as the hostname.
+
+**Acceptance Scenarios**:
+
+1. **Given** a build file declares a `postgres` container service and a container task with `needs: [postgres]`, **When** the task is executed, **Then** hammerkit starts the postgres container before the task and the task can reach it at hostname `postgres`.
+
+2. **Given** the postgres service has a `healthcheck` configured, **When** the task is about to start, **Then** hammerkit waits until the healthcheck exits with code 0 before launching the task container.
+
+### User Story 2 - Using a service from a local (non-container) task (Priority: P2)
+
+A developer runs a local task (no `image`) that needs a running service. Because the local task is not part of the container network, hammerkit injects connection details as environment variables so the process can still reach the service.
+
+**Why this priority**: Local tasks are common for development workflows and the env-variable injection is the only way they can reach services.
+
+**Independent Test**: Declare a container service and a local task that `needs` it. Run the local task and verify it receives `HAMMERKIT_<NAME>_HOST`, `HAMMERKIT_<NAME>_PORT`, and `HAMMERKIT_<NAME>_PORT_<containerPort>` environment variables.
+
+**Acceptance Scenarios**:
+
+1. **Given** a local task (no `image`) declares `needs: [postgres]` where postgres exposes port `5432`, **When** the task is executed, **Then** the process environment contains `HAMMERKIT_POSTGRES_HOST`, `HAMMERKIT_POSTGRES_PORT`, and `HAMMERKIT_POSTGRES_PORT_5432`.
+
+2. **Given** a service exposes multiple ports, **When** a local task needing it runs, **Then** a `HAMMERKIT_<NAME>_PORT_<containerPort>` variable is injected for each exposed container port.
+
+### User Story 3 - Manually controlling service lifetime with `up` / `down` (Priority: P2)
+
+A developer wants to keep a shared database running across several task runs without restarting it each time. They start the service with `hammerkit up` and stop it later with `hammerkit down`.
+
+**Why this priority**: Manual lifecycle control is important for developer-experience workflows where repeated task runs reuse a warm service.
+
+**Independent Test**: Run `hammerkit up`, verify the service container is running, then execute a task that needs it (it should skip starting the service), then run `hammerkit down` and verify the container stops.
+
+**Acceptance Scenarios**:
+
+1. **Given** a service is defined, **When** `hammerkit up` is executed, **Then** the service container starts and remains running.
+
+2. **Given** a running service started via `hammerkit up`, **When** `hammerkit down` is executed, **Then** the service container stops.
+
+### User Story 4 - Service-to-service and service-to-task dependencies (Priority: P3)
+
+A developer has a service that depends on another service (via `needs`) and/or requires a task to run first (via `deps`). Hammerkit resolves the dependency chain before starting the dependent service.
+
+**Why this priority**: Dependency chaining for services mirrors task dependencies and is a secondary but documented capability.
+
+**Independent Test**: Declare two services where one lists the other in `needs`, and the first also lists a task in `deps`. Verify hammerkit runs the task first, then starts the dependency service, then the dependent service.
+
+**Acceptance Scenarios**:
+
+1. **Given** service `api` declares `deps: [install]` and `needs: [postgres]`, **When** a task needing `api` is run, **Then** hammerkit runs `install` first, then starts `postgres`, then starts `api`.
+
+### Edge Cases
+
+- A local task that `needs` a Kubernetes-forwarded service receives the same `HAMMERKIT_<NAME>_*` environment variables, but hammerkit does not provide DNS resolution for it.
+- If no healthcheck is defined, hammerkit may start a dependent task before the service is fully ready.
+- A service name is uppercased when constructing environment variable names (e.g. service `my-db` becomes `HAMMERKIT_MY_DB_HOST`).
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST start all services listed in a task's `needs` before executing that task.
+- **FR-002**: System MUST expose services to container tasks via the container network using the service name as the DNS hostname.
+- **FR-003**: System MUST inject `HAMMERKIT_<NAME>_HOST`, `HAMMERKIT_<NAME>_PORT`, and `HAMMERKIT_<NAME>_PORT_<containerPort>` environment variables into local tasks for each needed service, where `<NAME>` is the uppercased service name.
+- **FR-004**: System MUST wait for a service's healthcheck command to exit with code 0 before launching any task that needs it, when a healthcheck is configured.
+- **FR-005**: System MUST support `hammerkit up` to start services independently of task execution.
+- **FR-006**: System MUST support `hammerkit down` to stop running services.
+- **FR-007**: System MUST resolve service `deps` (tasks) and `needs` (other services) before starting a service, applying the same dependency-ordering rules as for tasks.
+- **FR-008**: System MUST support both container services (image-based) and Kubernetes port-forwarding services within the same build file.
+
+### Key Entities
+
+- **Service**: A continuous, long-running process declared under the `services` key in a build file. Has a `name`, optional `needs` (other services), optional `deps` (tasks), and is either container-based or Kubernetes-based.
+- **Healthcheck**: An optional check attached to a container service. Contains a `cmd` executed inside the service container; exit code 0 means ready.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: A container task that `needs` a service starts only after that service is running (and its healthcheck passes, if present), verified across at least one postgres and one redis-style service.
+- **SC-002**: A local task that `needs` a service receives the correct host/port environment variables, confirmed by the task process reading them and connecting successfully.
+- **SC-003**: `hammerkit up` / `hammerkit down` start and stop services within a reasonable time, with no task execution triggered.
+- **SC-004**: Service dependency chains (service needing another service, service needing a task) resolve in the correct order with zero manual intervention.
+
+## Assumptions
+
+- The service name used as the DNS hostname is exactly as declared in the build file (case-sensitive for the network alias; uppercased only for the environment variable injection).
+- `HAMMERKIT_<NAME>_PORT` refers to the first/primary published port when a service exposes multiple ports.
+- Services are automatically stopped when they are no longer needed by any remaining task in the current run, unless started with `hammerkit up`.
+- The `--env` flag for selecting Kubernetes environments applies equally to Kubernetes-type services; container services are not environment-scoped.