hammerkit 1.6.0 → 1.7.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.

package/specs/task/extending/spec.md

@@ -1,74 +0,0 @@
-# Feature Specification: Task: Extending
-
-**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/extending.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Inherit a task from another build file (Priority: P1)
-
-A developer in a monorepo has a shared `build.tsc.yaml` that defines standard `install` and `build` tasks. In each package's `.hammerkit.yaml` they write a task with `extend: tsc:build` to inherit all properties of the base task (sources, generates, commands, dependencies) with the working directory of the current file. This eliminates copy-pasting task definitions across packages.
-
-**Why this priority**: Reducing duplication is the primary motivation for the extending feature and directly affects maintainability in larger projects.
-
-**Independent Test**: Define a base task in an included file and a task that extends it with no overrides; run the extending task and verify it behaves identically to the base task.
-
-**Acceptance Scenarios**:
-
-1. **Given** a task with `extend: <namespace>:<task>` and no additional properties, **When** the task is run, **Then** it executes with all properties of the base task and the working directory of the current build file.
-2. **Given** a task that extends a base task, **When** the base task defines `src`, `generates`, `deps`, and `cmds`, **Then** the extending task inherits all of those properties.
-
-### User Story 2 - Override properties in an extended task (Priority: P1)
-
-A developer extends a base task but needs to adjust specific properties — for example clearing all dependencies so the task runs standalone. They declare the overriding property alongside `extend`; the declared value replaces the inherited one.
-
-**Why this priority**: Inheritance without override capability would force developers to extend-and-copy, defeating the purpose.
-
-**Independent Test**: Extend a task that has `deps: [install]` and override with `deps: []`; run and verify the install task does not execute.
-
-**Acceptance Scenarios**:
-
-1. **Given** a task that extends a base task and declares `deps: []`, **When** the task is run, **Then** it runs without any dependency tasks, overriding the base `deps`.
-2. **Given** a task that extends a base task and declares a new `cmds` list, **When** the task is run, **Then** the overriding commands execute, not the base commands.
-3. **Given** a task that extends a base task and overrides only one property, **When** the task is run, **Then** all other properties are still inherited from the base task.
-
-### Edge Cases
-
-- The `extend` reference uses the `<namespace>:<task>` format where `namespace` matches an entry in the `includes` block of the same build file.
-- Extending a task that itself extends another task (multi-level extend) is not described in the docs; behavior is not specified here.
-- If the referenced base task or namespace does not exist, hammerkit should report an error at parse/plan time.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST accept an `extend` field on a task whose value is a `<namespace>:<taskName>` reference to a task in an included build file.
-- **FR-002**: A task with `extend` MUST inherit all properties of the referenced base task by default.
-- **FR-003**: The working directory of an extending task MUST be the directory of the current build file, not the included file.
-- **FR-004**: Any property declared on the extending task alongside `extend` MUST override the corresponding inherited property from the base task.
-- **FR-005**: Properties not overridden on the extending task MUST retain their inherited values from the base task.
-
-### Key Entities
-
-- **Base task**: A task defined in an included build file that serves as a template.
-- **Extending task**: A task in the current build file that references a base task via `extend` and optionally overrides specific properties.
-- **Include**: A top-level `includes` entry mapping a namespace to a build file path, enabling the `<namespace>:<task>` reference syntax.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: An extending task with no overrides produces the same observable behavior as running the base task directly, using the current file's working directory.
-- **SC-002**: An extending task with `deps: []` runs without executing any dependency tasks, even when the base task declares dependencies.
-- **SC-003**: An extending task that overrides one property inherits all other properties unchanged from the base task.
-
-## Assumptions
-
-- The `includes` block is required to bring the base file into scope under a namespace; the `extend` syntax `<namespace>:<task>` must match an entry in `includes`.
-- Only a single level of extension is documented; chained extension (a base that itself extends another) is treated as out of scope for this spec.
-- Property merging is a full replacement, not a deep merge — for example, overriding `deps` replaces the entire list, not appends to it.

package/specs/task/kubernetes/spec.md

@@ -1,125 +0,0 @@
-# Feature Specification: Task: 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/task/kubernetes.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Run tasks on a Kubernetes cluster (Priority: P1)
-
-A developer wants to run their hammerkit tasks on a Kubernetes cluster rather than the local Docker daemon. They declare an environment with a `kubernetes` target in the build file and pass `--env <name>` when running a task. Tasks execute as Kubernetes jobs, services run as deployments, and caching works identically to local runs.
-
-**Why this priority**: This is the headline feature introduced in 1.6.0; it enables cloud-based and reproducible remote execution from the same build file.
-
-**Independent Test**: Declare a kubernetes environment pointing to a reachable cluster context, run `hammerkit <task> --env <name>`, and verify the task pod appears in the cluster and the task completes successfully.
-
-**Acceptance Scenarios**:
-
-1. **Given** an `environments` block with a kubernetes target, **When** the user runs `hammerkit <task> --env <name>`, **Then** the task executes as a Kubernetes job in the specified cluster context.
-2. **Given** a service referenced by a task via `needs`, **When** the environment is kubernetes, **Then** the service runs as a Kubernetes deployment and its healthcheck is translated into readiness/liveness probes.
-3. **Given** no `--env` flag is passed, **When** the user runs a task, **Then** hammerkit uses the local Docker daemon regardless of declared environments.
-
-### User Story 2 - Configure the cluster connection (Priority: P1)
-
-An operator needs to specify which cluster context, namespace, and kubeconfig file to use. They fill in the kubernetes target fields; `context` is required and the rest default to sensible values.
-
-**Why this priority**: Without correct cluster targeting, tasks would run on the wrong cluster or fail to authenticate.
-
-**Independent Test**: Declare an environment with a specific `namespace`; run a task and verify the resulting job is created in that namespace.
-
-**Acceptance Scenarios**:
-
-1. **Given** a kubernetes target with only `context` set, **When** a task runs in that environment, **Then** hammerkit uses `$HOME/.kube/config` and the default namespace.
-2. **Given** a kubernetes target with `kubeconfig` and `namespace` set, **When** a task runs, **Then** the specified kubeconfig file and namespace are used.
-
-### User Story 3 - Expose services via ingresses (Priority: P2)
-
-An operator wants a deployed service to be reachable from outside the cluster. They add an `ingresses` entry under the kubernetes target with a hostname and service name. Hammerkit creates an Ingress (or Gateway API HTTPRoute) resource pointing to the service.
-
-**Why this priority**: Ingress configuration enables integration testing and end-to-end workflows that require external access to deployed services.
-
-**Independent Test**: Declare an ingress entry for a service, run in the kubernetes environment, and verify an Ingress resource with the correct host and service reference is created in the cluster.
-
-**Acceptance Scenarios**:
-
-1. **Given** an ingress entry with `host`, `service`, and `servicePort`, **When** the environment is activated, **Then** hammerkit creates a Kubernetes Ingress resource routing that host to the service.
-2. **Given** an ingress entry with `kind: httproute` and a `gateway` name, **When** the environment is activated, **Then** hammerkit creates a Gateway API HTTPRoute resource attached to the named Gateway.
-3. **Given** an ingress entry with both `ingress` and `httproute` kinds in the same list, **When** the environment is activated, **Then** both resource types are created.
-
-### User Story 4 - Target a remote Docker daemon (Priority: P3)
-
-A developer wants to run tasks against a remote Docker daemon instead of the local one. They declare an environment with a `docker` target and optionally supply a `host` address.
-
-**Why this priority**: Remote Docker is an alternative execution target that shares the environment declaration mechanism.
-
-**Independent Test**: Declare a docker environment with a `host` pointing to a remote daemon; run a task with `--env <name>` and verify it executes on the remote daemon.
-
-**Acceptance Scenarios**:
-
-1. **Given** a docker environment target with a `host` address, **When** `hammerkit <task> --env <name>` is run, **Then** the task executes against the remote Docker daemon at that address.
-
-### User Story 5 - Use `--env` with store and restore commands (Priority: P2)
-
-A CI engineer stores build cache from a cluster run and restores it on another machine. The `--env` flag is available on the store and restore CLI commands, not just execute.
-
-**Why this priority**: Remote cache round-tripping requires environment selection at storage time to address the right cluster outputs.
-
-**Independent Test**: Run `hammerkit store --env <name>` after a cluster-based build and verify the result is stored correctly.
-
-**Acceptance Scenarios**:
-
-1. **Given** a completed kubernetes-environment task run, **When** the user runs `hammerkit store --env <name>`, **Then** the task results from the cluster are stored.
-2. **Given** stored results from a cluster, **When** the user runs `hammerkit restore --env <name>`, **Then** the results are restored into the cluster environment.
-
-### Edge Cases
-
-- `context` is required for a kubernetes target; omitting it should cause a validation error.
-- `kind: httproute` requires Gateway API CRDs and a `Gateway` resource to be installed in the cluster; hammerkit does not install these prerequisites.
-- The `gateway` field is required when `kind: httproute` is used; `gatewayNamespace` is optional.
-- The same environment declaration supplies cluster connection details for port-forward Kubernetes services (described in the service/kubernetes page), avoiding repetition.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST accept a top-level `environments` block where each entry targets either `kubernetes` or `docker`.
-- **FR-002**: The system MUST accept a `--env <name>` CLI flag on the execute, store, and restore commands.
-- **FR-003**: When `--env` is not supplied, the system MUST use the local Docker daemon.
-- **FR-004**: A kubernetes target MUST require a `context` field identifying the kube context (cluster + user).
-- **FR-005**: A kubernetes target MUST support optional `namespace`, `kubeconfig`, and `ingresses` fields.
-- **FR-006**: When `kubeconfig` is not specified, the system MUST default to `$HOME/.kube/config`.
-- **FR-007**: The system MUST execute tasks as Kubernetes jobs and container services as Kubernetes deployments when running in a kubernetes environment.
-- **FR-008**: A service healthcheck MUST be translated into Kubernetes readiness and liveness probes on the corresponding deployment.
-- **FR-009**: The system MUST support an `ingresses` list on a kubernetes target, creating either an Ingress or a Gateway API HTTPRoute resource per entry.
-- **FR-010**: An ingress entry MUST require `host` and `service` fields; `kind` (default `ingress`), `servicePort`, and `path` are optional.
-- **FR-011**: An `httproute` ingress entry MUST require a `gateway` field; `gatewayNamespace` is optional.
-- **FR-012**: A docker environment target MUST support an optional `host` field for a remote Docker daemon address.
-- **FR-013**: Task caching MUST function identically in kubernetes environments as in local docker runs.
-
-### Key Entities
-
-- **Environment**: A named entry in `environments` specifying either a `kubernetes` or `docker` execution target.
-- **Kubernetes target**: Configuration for cluster execution: `context` (required), `namespace`, `kubeconfig`, `ingresses`.
-- **Docker target**: Configuration for docker execution: `host` (optional).
-- **Ingress entry**: Route configuration with `kind`, `host`, `service`, `servicePort`, `path`, `gateway`, `gatewayNamespace`.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A task run with `--env <kubernetes-env>` creates a job in the target cluster and produces the same output as a local run.
-- **SC-002**: A service with a healthcheck deployed via a kubernetes environment has readiness and liveness probes on its deployment.
-- **SC-003**: An ingress entry with `kind: ingress` creates a Kubernetes Ingress resource with the correct host and backend service.
-- **SC-004**: An ingress entry with `kind: httproute` creates a Gateway API HTTPRoute resource attached to the specified Gateway.
-- **SC-005**: Without `--env`, tasks run on the local Docker daemon regardless of declared environments.
-
-## Assumptions
-
-- "Same caching behavior" means checksum/modify-date/none methods and remote backends all work the same way in a kubernetes environment as locally.
-- The kubernetes environment feature was introduced in hammerkit 1.6.0; earlier versions do not support it.
-- Port-forward Kubernetes services (described separately in service/kubernetes.md) can reuse the cluster connection declared in an environment via `--env`, but this page does not specify that detail further.

package/specs/task/needs/spec.md

@@ -1,59 +0,0 @@
-# Feature Specification: Task: Needs
-
-**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/needs.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Start a service before a task (Priority: P1)
-
-A developer has a task that requires a database to be running. They declare the database service in the `services` block with a healthcheck command and reference it in the task's `needs` list. When the task is executed, hammerkit starts the service automatically and waits until the healthcheck passes before running any task commands.
-
-**Why this priority**: Tasks that depend on services would fail silently or non-deterministically without this coordination mechanism.
-
-**Independent Test**: Define a service with a healthcheck and a task with `needs: [<service>]`; run the task and verify the service is reachable before the first command executes.
-
-**Acceptance Scenarios**:
-
-1. **Given** a service with a healthcheck and a task that lists that service in `needs`, **When** the user runs the task, **Then** hammerkit starts the service and waits for the healthcheck to pass before executing the task's commands.
-2. **Given** a task with `needs: [postgres]` and a postgres service whose healthcheck fails continuously, **When** the task is run, **Then** the task does not start and hammerkit reports that the service is not ready.
-3. **Given** multiple tasks that each list the same service in `needs`, **When** those tasks run together, **Then** the service is started once and shared rather than started per-task.
-
-### Edge Cases
-
-- A service referenced in `needs` but not defined in the `services` block should cause an error at parse/plan time.
-- If no healthcheck is defined on a service, hammerkit starts the task immediately after launching the service container without readiness gating.
-- A task with an empty `needs: []` list is treated the same as a task with no `needs` field.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST accept a `needs` list of service names on any task.
-- **FR-002**: The system MUST start every service listed in a task's `needs` before executing that task's commands.
-- **FR-003**: When a service declares a `healthcheck`, the system MUST wait for the healthcheck to succeed before the dependent task starts.
-- **FR-004**: The system MUST NOT start a task whose `needs` services have not yet passed their healthchecks.
-
-### Key Entities
-
-- **Service**: A long-running container process declared in the top-level `services` block. Key attributes: `image`, `healthcheck` (optional, with `cmd`).
-- **Needs**: A list of service names on a task that declares runtime dependencies on those services.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A task with `needs: [postgres]` does not execute its first command until the postgres service's healthcheck returns success.
-- **SC-002**: When a service healthcheck never passes, the dependent task never starts and hammerkit reports a failure.
-- **SC-003**: A service listed in `needs` by multiple tasks is started exactly once per run.
-
-## Assumptions
-
-- `needs` expresses a runtime service dependency, distinct from `deps` which expresses a task execution dependency.
-- Healthcheck polling interval and timeout are implementation details not specified in the docs; they are assumed to be reasonable defaults.
-- Services are stopped by hammerkit after all tasks that need them have completed, though the exact lifecycle is not described on this page.

package/specs/task/spec.md

@@ -1,87 +0,0 @@
-# Feature Specification: Task: 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/task/README.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Run a minimal task (Priority: P1)
-
-A developer defines a task with only a list of commands in `.hammerkit.yaml` and runs it. Hammerkit executes each command in sequence. No source or output declarations are required for the most basic use case.
-
-**Why this priority**: This is the entry-point experience; every other feature builds on it.
-
-**Independent Test**: Create a `.hammerkit.yaml` with a single `echo` command task and run it — the output should appear in the terminal.
-
-**Acceptance Scenarios**:
-
-1. **Given** a `.hammerkit.yaml` with a task containing only `cmds`, **When** the user runs `hammerkit <task>`, **Then** each command executes in order and the process exits with the command's exit code.
-
-### User Story 2 - Declare source files to enable caching (Priority: P1)
-
-A developer adds a `src` list to a task. On subsequent runs where none of the listed files have changed, hammerkit skips execution entirely and reports the task as cached.
-
-**Why this priority**: Source-based caching is the primary performance mechanism for incremental builds.
-
-**Independent Test**: Run the task twice with no file changes; the second run must be skipped/cached.
-
-**Acceptance Scenarios**:
-
-1. **Given** a task with `src` files defined, **When** those files are unchanged since the last successful run, **Then** the task is skipped.
-2. **Given** a task with `src` files defined, **When** one source file changes, **Then** the task re-executes.
-
-### User Story 3 - Declare generated output files (Priority: P2)
-
-A developer adds a `generates` list so hammerkit knows which output directories a task produces. Generated files can optionally be exported back to the workspace or reset before each run.
-
-**Why this priority**: Tracking outputs enables archiving/restore and correct incremental behaviour.
-
-**Independent Test**: Run a container task with `export: true` on a generate path and verify the directory appears in the host workspace after the run.
-
-**Acceptance Scenarios**:
-
-1. **Given** a container task with `generates` and `export: true`, **When** the task completes, **Then** the generated directory is copied into the host workspace.
-2. **Given** a task with `generates` and `resetOnChange: true`, **When** the task re-runs after a source change, **Then** the output directory is wiped before execution begins.
-3. **Given** a container task with `generates` but no `export` flag, **When** the task completes, **Then** the output stays inside the container volume and is not copied to the host.
-
-### Edge Cases
-
-- A task with no `src` declaration is always executed (never skipped by caching).
-- `resetOnChange: true` only wipes the directory when the task actually re-runs (i.e. cache miss); it has no effect when the task is skipped.
-- `export: true` is only meaningful for container tasks; for local tasks outputs are already on the host filesystem.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST execute the commands of a task in the order they are declared under `cmds`.
-- **FR-002**: The system MUST accept a `src` list of files, directories, or glob patterns on a task and use it to determine whether the task can be skipped.
-- **FR-003**: The system MUST accept a `generates` list on a task that identifies output files or directories produced by the task.
-- **FR-004**: When a generate entry carries `export: true`, the system MUST copy that path from the container volume into the host workspace after the task succeeds.
-- **FR-005**: When a generate entry carries `resetOnChange: true`, the system MUST wipe that output directory before re-executing the task.
-- **FR-006**: The system MUST support an optional `description` field on a task for human-readable documentation.
-
-### Key Entities
-
-- **Task**: The primary unit of work. Key attributes: `cmds` (required), `src` (optional), `generates` (optional), `description` (optional).
-- **Generate entry**: An output path, optionally decorated with `export` (boolean) and `resetOnChange` (boolean).
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A task with no `src` always runs when invoked.
-- **SC-002**: A task with unchanged `src` files is skipped on the second run without executing any command.
-- **SC-003**: After a container task with `export: true` completes, the generated path exists on the host filesystem.
-- **SC-004**: After a container task with `resetOnChange: true` re-runs, no files from a previous run remain in the output directory before the new commands execute.
-
-## Assumptions
-
-- The minimal task form (only `cmds`) is always a local (non-container) task unless an `image` is specified.
-- "Generates" store output inside a container volume by default; the `export` flag is only relevant for container tasks.
-- The `description` field is display-only and does not affect execution.

package/specs/task/watching/spec.md

@@ -1,69 +0,0 @@
-# Feature Specification: Task: Watching
-
-**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/watching.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Restart a task automatically on source file changes (Priority: P1)
-
-A developer runs an API server task and wants it to restart whenever the source code changes. They run `hammerkit <task> --watch`. Hammerkit watches the task's declared `src` files and folders; when a change is detected it restarts the task.
-
-**Why this priority**: Watch mode is the primary developer-experience feature for iterative development workflows.
-
-**Independent Test**: Start a task with `--watch` and a `src` folder; modify a file in the folder and observe that the task process is terminated and restarted.
-
-**Acceptance Scenarios**:
-
-1. **Given** a task with `src` defined and the `--watch` flag, **When** a file in `src` changes, **Then** hammerkit terminates the running task and restarts it.
-2. **Given** a task with `src` defined and the `--watch` flag, **When** no files change, **Then** the task continues running without interruption.
-
-### User Story 2 - Mark a self-managing task as continuous (Priority: P2)
-
-A developer uses Angular CLI's `ng serve` which handles its own file watching and incremental rebuilding internally. They mark the task with `continuous: true`. When watch mode is active, hammerkit does not watch the `src` directory for that task, allowing the tool to manage its own restart cycle.
-
-**Why this priority**: Self-managing tasks (Angular, webpack --watch, etc.) would otherwise be redundantly restarted by hammerkit on top of their own internal watching, causing conflicts.
-
-**Independent Test**: Mark a task `continuous: true` and run with `--watch`; modify a source file and verify hammerkit does NOT restart the task process (the task handles its own reload).
-
-**Acceptance Scenarios**:
-
-1. **Given** a task with `continuous: true` and the `--watch` flag, **When** a file in `src` changes, **Then** hammerkit does NOT restart the task process.
-2. **Given** a task with `continuous: true` but WITHOUT `--watch`, **When** the task is run normally, **Then** the `continuous` flag has no visible effect on single-run behavior.
-3. **Given** a mix of continuous and non-continuous tasks in watch mode, **When** a source file for the non-continuous task changes, **Then** only the non-continuous task is restarted.
-
-### Edge Cases
-
-- A task without `src` declared has nothing to watch; behavior with `--watch` and no `src` is not specified (assumed to run once and stay alive without restart triggers).
-- `continuous: true` only suppresses hammerkit-level file watching; it does not affect how the task's process itself behaves.
-- Watch mode with a container task follows the same restart semantics as a local task.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST support a `--watch` CLI flag on the execute command.
-- **FR-002**: When `--watch` is active, the system MUST monitor the `src` files and folders of a task for changes.
-- **FR-003**: When a change is detected in watched sources, the system MUST terminate the running task process and restart it.
-- **FR-004**: The system MUST accept a `continuous: true` field on a task.
-- **FR-005**: When a task has `continuous: true` and watch mode is active, the system MUST NOT watch the task's `src` for changes or restart it.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: Modifying a source file of a watched non-continuous task causes the task to restart within a reasonable detection window.
-- **SC-002**: Modifying a source file of a watched continuous task does NOT cause hammerkit to restart that task process.
-- **SC-003**: A task without `continuous: true` runs and restarts under `--watch` as expected.
-
-## Assumptions
-
-- Watch mode monitors the same `src` paths used for caching; the two features share source declarations.
-- The file-system polling or event mechanism used for watching is an implementation detail not described in the docs.
-- `continuous: true` is intended for tasks that have their own internal watch loop (e.g., webpack, ng serve, jest --watch).
-- Watch mode operates for the lifetime of the hammerkit process; Ctrl-C stops watching and terminates all running tasks.