hammerkit 1.6.0 → 1.7.0

package/specs/cli/validate/spec.md

@@ -1,70 +0,0 @@
-# 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

@@ -1,91 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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

@@ -1,97 +0,0 @@
-# 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

@@ -1,105 +0,0 @@
-# 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.

package/specs/task/caching/spec.md

@@ -1,107 +0,0 @@
-# Feature Specification: Task: Caching
-
-**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/task/caching.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Skip unchanged tasks automatically (Priority: P1)
-
-A developer runs their build repeatedly. Tasks whose source files have not changed since the last successful run are detected as up-to-date and skipped, saving time.
-
-**Why this priority**: Caching is the primary mechanism that makes hammerkit practical for incremental development workflows.
-
-**Independent Test**: Run a task with `src` defined twice with no file changes; confirm the second run reports the task as skipped and no commands execute.
-
-**Acceptance Scenarios**:
-
-1. **Given** a task with `src` files defined, **When** those files have not changed since the last successful run, **Then** the task is skipped.
-2. **Given** a task with `src` files defined, **When** at least one source file has changed, **Then** the task re-executes.
-3. **Given** a task whose dependency has no `src` defined (always runs), **When** the downstream task has `src` defined, **Then** the downstream task is also executed (cannot be skipped when an upstream task was not skipped).
-
-### User Story 2 - Choose a cache method per task (Priority: P2)
-
-A developer wants finer control over how staleness is detected. They set `cache: modify-date` on a task to use file modification timestamps instead of content checksums, or `cache: none` to disable caching for a specific task.
-
-**Why this priority**: Different tasks have different performance/correctness trade-offs for cache detection.
-
-**Independent Test**: Set `cache: none` on a task with `src` defined and verify it always re-executes regardless of source changes.
-
-**Acceptance Scenarios**:
-
-1. **Given** `cache: checksum` on a task, **When** source file content is identical but the modification timestamp has changed, **Then** the task is skipped.
-2. **Given** `cache: modify-date` on a task, **When** a source file's modification timestamp has changed, **Then** the task re-executes even if content is the same.
-3. **Given** `cache: none` on a task, **When** the task is invoked, **Then** it always re-executes regardless of source state.
-
-### User Story 3 - Override the default cache method globally at runtime (Priority: P2)
-
-A CI engineer wants to run all tasks with checksum-based caching regardless of the per-task defaults. They pass `--cache checksum` on the CLI to override the default for all tasks that did not set an explicit cache method.
-
-**Why this priority**: CI environments benefit from a reliable, content-based cache independent of local developer machine defaults.
-
-**Independent Test**: Run with `--cache none` and verify all tasks without an explicit `cache` field re-execute.
-
-**Acceptance Scenarios**:
-
-1. **Given** tasks with no explicit `cache` field, **When** `hammerkit build --cache modify-date` is run, **Then** all those tasks use modify-date caching.
-2. **Given** a task with an explicit `cache: checksum`, **When** `hammerkit build --cache modify-date` is run, **Then** that task continues to use checksum caching (explicit value wins).
-
-### User Story 4 - Use a remote cache backend to share results across machines (Priority: P3)
-
-A team wants CI and developer machines to share build results. They declare a named cache in the build file with an S3 backend and reference it from their tasks. Hammerkit pulls a cached result before running the task and pushes a new result after a successful run.
-
-**Why this priority**: Remote caching eliminates redundant work in distributed teams and CI/CD pipelines.
-
-**Independent Test**: Configure an S3-backed cache, run the task on one machine, then run on a second machine that has not built locally and confirm the task is skipped via the remote cache.
-
-**Acceptance Scenarios**:
-
-1. **Given** a task with a named cache pointing to a remote backend, **When** a matching cache entry exists remotely, **Then** hammerkit pulls the result and skips task execution.
-2. **Given** a task with a named cache pointing to a remote backend, **When** no matching entry exists remotely and the task runs successfully, **Then** hammerkit pushes the result to the remote backend.
-
-### Edge Cases
-
-- Source glob patterns using `**` do not traverse symlinked directories.
-- Using a large directory such as `node_modules` as a source is explicitly discouraged because recursive traversal is expensive.
-- A task can only be skipped if all of its dependencies before it were also skipped; a single non-skipped ancestor forces the task to re-execute.
-- The default cache method is `modify-date` locally and `checksum` in CI (environment-dependent).
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST accept a `src` list of files, directories, and glob patterns on a task and use them to determine skip eligibility.
-- **FR-002**: The system MUST skip a task when all its sources are unchanged and all its dependency tasks were also skipped.
-- **FR-003**: The system MUST support three cache methods: `checksum` (content hash), `modify-date` (file mtime), and `none` (always execute).
-- **FR-004**: The system MUST support a `cache` field on a task accepting either a shorthand method string or an object with `name` and optional `method` fields.
-- **FR-005**: The system MUST support a `--cache <method>` CLI flag that sets the default method for all tasks that did not declare an explicit `cache` field.
-- **FR-006**: An explicit `cache` value on a task MUST take precedence over the `--cache` flag.
-- **FR-007**: The system MUST support named caches with remote backends (at minimum S3 and S3-compatible stores).
-- **FR-008**: When a remote cache backend is configured and a cache hit exists remotely, the system MUST pull and restore the result without executing the task.
-- **FR-009**: After a successful task run with a remote backend, the system MUST push the result to the remote backend.
-- **FR-010**: Glob patterns in `src` MUST support the node-glob pattern set including `*`, `?`, `[...]`, `!(…)`, `?(…)`, `+(…)`, `*(…)`, `@(…)`, and `**`.
-
-### Key Entities
-
-- **Cache entry**: A record of a successful task run keyed by source fingerprint, associated with a cache method and optionally a named backend.
-- **Named cache**: A top-level `caches` declaration with an optional remote backend (`local` or `s3`).
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A task with unchanged sources is skipped on the second consecutive run with zero commands executed.
-- **SC-002**: Changing a single source file causes exactly the affected task (and its dependents) to re-execute on the next run.
-- **SC-003**: `--cache none` causes all tasks without an explicit `cache` field to execute unconditionally.
-- **SC-004**: With an S3 remote backend, a task result produced on machine A is reused on machine B without re-executing the task commands.
-
-## Assumptions
-
-- The environment-dependent default (modify-date locally, checksum in CI) is determined by whether hammerkit detects a CI environment variable (e.g., `CI=true`).
-- Redeclaring the built-in `default` cache to use a remote backend affects all tasks that reference the default cache, as described in the build-file caches documentation.
-- The `s3` backend covers S3-compatible stores (MinIO, Cloudflare R2, Google Cloud Storage); no additional backend types are documented for 1.6.0.