hammerkit 1.6.0 → 1.8.0

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.

package/specs/task/container/spec.md

@@ -1,118 +0,0 @@
-# Feature Specification: Task: 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/task/container.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Run a task inside a container image (Priority: P1)
-
-A developer wants to build their project without installing Node.js locally. They add `image: node:14.16.0` to the task definition and hammerkit executes the task's commands inside a container using that image.
-
-**Why this priority**: Container execution is the core cross-platform isolation feature of hammerkit.
-
-**Independent Test**: Define a task with `image` set and a command that prints the Node version; verify the output matches the version in the image, not any locally installed Node.
-
-**Acceptance Scenarios**:
-
-1. **Given** a task with an `image` property, **When** the task is run, **Then** all commands execute inside a container created from that image.
-2. **Given** a task with `image` but no `src` or `mounts`, **When** the task runs, **Then** the container has no access to host files.
-
-### User Story 2 - Make source files available inside the container (Priority: P1)
-
-A developer's container task needs to read project files. They declare those files and folders in `src`; hammerkit mounts them into the container automatically so commands can access them.
-
-**Why this priority**: Without file access the container task cannot read inputs and is not useful.
-
-**Independent Test**: Add `src` files to a container task and verify a command inside the container can read those files.
-
-**Acceptance Scenarios**:
-
-1. **Given** a container task with `src` files listed, **When** the task executes, **Then** those files are accessible at their expected paths inside the container.
-2. **Given** a container task whose dependency task declares `src` and `generates`, **When** the dependent task executes, **Then** those dependency paths are also mounted automatically without being listed again.
-
-### User Story 3 - Persist output files across runs using generates (Priority: P2)
-
-A developer's container task produces `node_modules`. They declare `node_modules` under `generates` so hammerkit persists it in a container volume between runs, enabling caching of the installed packages.
-
-**Why this priority**: Without `generates`, outputs are lost when the container exits; re-runs would redo all work.
-
-**Independent Test**: Run an install task in a container with `node_modules` in `generates`; stop hammerkit and run again — the second run should be cached and `node_modules` should still be present.
-
-**Acceptance Scenarios**:
-
-1. **Given** a container task with a path in `generates`, **When** the task completes, **Then** the output is preserved in a container volume for the next run.
-2. **Given** a container task with `generates` and `export: true`, **When** the task completes, **Then** the generated files are also copied to the host workspace.
-
-### User Story 4 - Mount additional files and directories (Priority: P2)
-
-A developer needs to give the container access to files that are neither source inputs nor generated outputs (e.g., a credential file or a shared cache directory). They use `mounts` with relative paths, absolute paths, or `$PWD`-relative expressions.
-
-**Why this priority**: Not all container inputs fit the source/generate model; mounts fill that gap.
-
-**Independent Test**: Add a mount to a container task and verify the mounted path is accessible inside the container.
-
-**Acceptance Scenarios**:
-
-1. **Given** a container task with a relative `mounts` entry, **When** the task runs, **Then** the relative path is mounted into the container.
-2. **Given** a container task with an absolute `mounts` entry, **When** the task runs, **Then** the absolute path is mounted into the container.
-3. **Given** a container task with a `$PWD`-style `mounts` entry (e.g., `$PWD/.npm:/.npm`), **When** the task runs, **Then** the path is expanded and mounted at the specified target path.
-
-### User Story 5 - Override the execution shell (Priority: P3)
-
-A developer's commands require bash-specific syntax. They set `shell: bash` on the task and commands are invoked with bash instead of the default `sh`.
-
-**Why this priority**: Some commands or scripts require a specific shell; the default `sh` is too restrictive for some use cases.
-
-**Independent Test**: Set `shell: bash` and use a bash-only feature (`$RANDOM`); verify the command succeeds inside the container.
-
-**Acceptance Scenarios**:
-
-1. **Given** a container task with `shell: bash`, **When** a command uses bash-specific syntax, **Then** it executes successfully.
-2. **Given** a container task without a `shell` property, **When** commands run, **Then** they are executed with `sh`.
-
-### Edge Cases
-
-- A container task with no `src`, `generates`, or `mounts` can still run but has no access to host files.
-- File permissions: commands in a container run with the same UID/GID as the local user; hammerkit sets the owner of the working directory and all mounts to that UID/GID before each task run.
-- Sources and generates of all dependency tasks are automatically mounted; this reduces the need for explicit `mounts` entries.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST accept an `image` property on a task and execute all `cmds` inside a container created from that image.
-- **FR-002**: The system MUST mount all `src` files and directories into the container at task startup so they are accessible inside the container.
-- **FR-003**: The system MUST persist paths listed in `generates` in a container volume across runs.
-- **FR-004**: The system MUST automatically mount the `src` and `generates` paths of all dependency tasks into a dependent container task.
-- **FR-005**: The system MUST accept a `mounts` list supporting relative paths, absolute paths, and `$PWD`-prefixed expressions with optional target path suffixes.
-- **FR-006**: The system MUST default to `sh` as the command execution shell for container tasks.
-- **FR-007**: The system MUST accept a `shell` property on a task to override the execution shell.
-- **FR-008**: The system MUST run container commands with the same UID/GID as the host user and set ownership of the working directory and mounts accordingly before each run.
-
-### Key Entities
-
-- **Container task**: A task with an `image` property. Additional attributes: `shell` (optional), `mounts` (optional list), `src` (optional), `generates` (optional).
-- **Mount entry**: A string specifying a host path (relative, absolute, or `$PWD`-prefixed) optionally followed by `:` and a container target path.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A container task command that prints the runtime version outputs the version from the declared image, not the host.
-- **SC-002**: Files listed in `src` are readable inside the container during task execution.
-- **SC-003**: A path listed in `generates` persists between separate hammerkit invocations without requiring re-installation.
-- **SC-004**: A container task with `export: true` on a generate path results in that directory appearing on the host filesystem after the run.
-- **SC-005**: Files created inside the container are owned by the host user's UID/GID on the host filesystem.
-
-## Assumptions
-
-- Container execution uses the local Docker daemon unless an environment is selected (see kubernetes.md).
-- The working directory inside the container mirrors the host project directory structure.
-- `$PWD` in mount expressions is expanded to the host working directory at task execution time.
-- The `export` and `resetOnChange` flags on generate entries are described on the Task Overview page and apply equally to container tasks.

package/specs/task/dependencies/spec.md

@@ -1,70 +0,0 @@
-# Feature Specification: Task: Dependencies
-
-**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/dependencies.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Chain tasks with dependencies (Priority: P1)
-
-A developer has three tasks — `install`, `build`, and `publish` — where each step must complete before the next starts. They declare `deps` on each downstream task. When running `hammerkit publish`, hammerkit resolves the full chain and executes each task in dependency order.
-
-**Why this priority**: Dependency ordering is the foundational orchestration primitive; without it users must run tasks manually in sequence.
-
-**Independent Test**: Define a three-task chain and run the last one; observe that all three execute in correct order.
-
-**Acceptance Scenarios**:
-
-1. **Given** tasks A, B, C where B depends on A and C depends on B, **When** the user runs `hammerkit C`, **Then** A executes first, then B, then C.
-2. **Given** a dependency chain where task A fails, **When** the user runs `hammerkit C`, **Then** B and C are not executed and the run aborts with a failure.
-3. **Given** a dependency is already cached (sources unchanged), **When** the user runs a downstream task, **Then** the cached dependency is skipped and the downstream task still runs.
-
-### User Story 2 - Deep dependency chains (Priority: P2)
-
-A developer in a monorepo builds deeply nested dependency graphs. Hammerkit resolves chains of arbitrary depth as long as there are no cycles.
-
-**Why this priority**: Monorepos commonly have multi-level dependency trees.
-
-**Independent Test**: Create a 5-level dependency chain and confirm all levels execute in the correct order.
-
-**Acceptance Scenarios**:
-
-1. **Given** a dependency graph N levels deep with no cycles, **When** the leaf task is invoked, **Then** all ancestors execute in topological order.
-2. **Given** a build file where task A depends on task B and task B depends on task A, **When** any task in the cycle is invoked, **Then** hammerkit reports an error and does not execute any task.
-
-### Edge Cases
-
-- A task with an empty `deps: []` list is treated the same as a task with no `deps` field.
-- If any dependency in the chain fails, all pending downstream tasks are aborted.
-- Circular dependency graphs (loops) are explicitly prohibited and must be detected at parse/plan time.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST accept a `deps` list of task names on any task.
-- **FR-002**: The system MUST execute all tasks listed in `deps` before executing the dependent task.
-- **FR-003**: The system MUST abort execution of all pending tasks when any dependency task fails.
-- **FR-004**: The system MUST support arbitrarily deep dependency chains.
-- **FR-005**: The system MUST detect and reject cyclic dependency graphs (loops).
-- **FR-006**: A dependency task that is cached (all sources unchanged) MUST be skipped without re-executing, and downstream tasks that still need to run MUST continue normally.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: Running a task with a two-level dependency chain results in the dependency executing first, followed by the requested task.
-- **SC-002**: When a dependency fails, no tasks that depend on it (directly or transitively) are executed.
-- **SC-003**: Cyclic dependencies cause hammerkit to exit with an error before executing any command.
-- **SC-004**: A cached dependency does not re-execute; its downstream task still executes if needed.
-
-## Assumptions
-
-- `deps` values must reference tasks defined within the same build file or an included build file; cross-build-file references follow the include/namespace conventions described elsewhere.
-- Dependency resolution is eager: all dependencies of a task are resolved before that task starts, not lazily during execution.
-- Parallel execution of independent siblings within a dependency graph is outside the scope of this page and is not specified here.