hammerkit 1.6.0-alpha.3 → 1.7.0

package/specs/cli/execute/spec.md

@@ -1,101 +0,0 @@
-# Feature Specification: CLI: execute
-
-**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/execute.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Running a task by name (Priority: P1)
-
-A developer wants to build a specific artifact. They run `hammerkit <task-name>` (or `hammerkit run <task-name>`) and hammerkit executes that task and all its declared dependencies inside the appropriate containers.
-
-**Why this priority**: Executing tasks is the core purpose of the tool; all other features support this.
-
-**Independent Test**: Given a build file with a task named `example`, run `hammerkit example` and verify it completes successfully and produces the expected output.
-
-**Acceptance Scenarios**:
-
-1. **Given** a build file with a task `build`, **When** the user runs `hammerkit build`, **Then** hammerkit executes the `build` task (and its dependencies) and exits with code 0 on success.
-
-2. **Given** a build file with a task `build`, **When** the user runs `hammerkit run build`, **Then** the result is identical to running `hammerkit build`.
-
-3. **Given** a task name that does not exist in the build file, **When** the user runs `hammerkit <nonexistent>`, **Then** hammerkit exits with a non-zero code and a meaningful error message.
-
-### User Story 2 - Filtering tasks by labels (Priority: P2)
-
-A monorepo developer wants to run only the iOS build tasks. They use `--filter` to include only tasks with a matching label or `--exclude` to skip tasks with a given label, so unrelated tasks are not executed.
-
-**Why this priority**: Label-based filtering is a key scalability feature for large builds with many tasks.
-
-**Independent Test**: Given a build file with tasks labeled `build=ios` and `build=android`, run `hammerkit -f build=ios` and verify only the iOS tasks (and their dependencies) execute.
-
-**Acceptance Scenarios**:
-
-1. **Given** tasks with label `type=build` and tasks without that label, **When** the user runs `hammerkit -f type=build`, **Then** only tasks matching `type=build` are executed; dependent tasks without that label may still run to satisfy dependencies.
-
-2. **Given** tasks with label `build=ios`, **When** the user runs `hammerkit -e build=ios`, **Then** tasks with `build=ios` are excluded; if a dependent task also matches the excluded label, it is excluded too.
-
-3. **Given** multiple label filters, **When** the user provides multiple `-f` arguments, **Then** only tasks matching all specified labels are included.
-
-### User Story 3 - Controlling concurrency, caching, and log mode (Priority: P3)
-
-A developer running on a slow machine wants to limit parallel workers, or a CI engineer wants checksum-based caching and grouped log output. They pass the relevant flags to tune hammerkit's behavior for their environment.
-
-**Why this priority**: These are power-user options that improve CI reliability and local performance but are not needed for basic usage.
-
-**Independent Test**: Run `hammerkit run <task> --concurrency 1` and verify tasks execute sequentially (no interleaved log lines from parallel workers).
-
-**Acceptance Scenarios**:
-
-1. **Given** a build file with multiple independent tasks, **When** the user runs `hammerkit -c 1`, **Then** tasks execute one at a time rather than in parallel.
-
-2. **Given** a CI environment, **When** hammerkit detects CI, **Then** `--log` defaults to `live` and `--cache` defaults to `checksum` without requiring explicit flags.
-
-3. **Given** a local (non-CI) environment, **When** hammerkit runs without explicit `--log` or `--cache` flags, **Then** `--log` defaults to `interactive` and `--cache` defaults to `modify-date`.
-
-4. **Given** a task with `src` files, **When** `--cache none` is specified, **Then** the task runs unconditionally without checking whether inputs have changed.
-
-5. **Given** a task with `src` files that have not changed, **When** `--watch` is specified, **Then** hammerkit watches those files and re-executes the task when they change.
-
-### Edge Cases
-
-- Specifying both `--filter` and `--exclude` with overlapping labels must resolve deterministically (exclude takes precedence for matched tasks).
-- `--concurrency 0` or negative values should be rejected with a clear error.
-- `--env <name>` is accepted but its behavior is defined by the environment configuration, not by the execute command itself.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST execute a task by name when the user supplies the task name as the first argument (with or without the explicit `run` subcommand).
-- **FR-002**: System MUST execute all declared dependency tasks before the named task.
-- **FR-003**: System MUST support label-based inclusion filtering via `-f / --filter <key=value>` where only tasks matching the label are directly executed (dependencies may still run).
-- **FR-004**: System MUST support label-based exclusion filtering via `-e / --exclude <key=value>` where tasks (and their dependents) matching the label are skipped.
-- **FR-005**: System MUST support a `-c / --concurrency <number>` option controlling the number of parallel worker threads (default: 4).
-- **FR-006**: System MUST support a `-w / --watch` flag that re-executes tasks when their source files change.
-- **FR-007**: System MUST support a `--cache <method>` option with choices `checksum`, `modify-date`, and `none`.
-- **FR-008**: System MUST support a `-l / --log <mode>` option with choices `interactive`, `live`, and `grouped`.
-- **FR-009**: System MUST default `--log` to `interactive` and `--cache` to `modify-date` outside CI, and to `live` and `checksum` inside CI.
-- **FR-010**: System MUST support an `--env <name>` option to target a configured named environment.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: `hammerkit <task>` and `hammerkit run <task>` produce identical exit codes and output for the same task.
-- **SC-002**: With `-f type=build`, only tasks bearing the `type=build` label are directly invoked; the set of executed tasks is smaller than running without the filter.
-- **SC-003**: With `-e build=ios`, no task bearing `build=ios` appears in the execution log.
-- **SC-004**: With `-c 1`, task execution log lines are never interleaved across concurrent workers.
-- **SC-005**: With `--cache none`, a task runs even when no source files have changed since the last run.
-
-## Assumptions
-
-- `hammerkit` with no subcommand and no task name runs all tasks (or the default task if one is defined); the docs show a task name is required for named execution.
-- `--filter` and `--exclude` accept `key=value` pairs; partial-key matching (e.g., filtering by key name only) is not documented and assumed unsupported.
-- The `--watch` flag watches the `src` files declared on the task; the exact file-watching mechanism is an implementation detail.
-- CI is detected automatically via standard CI environment variables (e.g., `CI=true`); this is an informed guess not explicitly stated in the docs.

package/specs/cli/init/spec.md

@@ -1,64 +0,0 @@
-# Feature Specification: CLI: init
-
-**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/init.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Bootstrapping a new project (Priority: P1)
-
-A developer starts a brand-new project and wants to adopt hammerkit. They run `hammerkit init` in the project root, which creates a ready-to-edit `.hammerkit.yaml` with a working example task and appends the hammerkit cache directory to `.gitignore` so build artifacts are not accidentally committed.
-
-**Why this priority**: `init` is the mandatory first step for every new hammerkit user; without it the rest of the tool cannot be used.
-
-**Independent Test**: In an empty directory, run `hammerkit init` and verify that `.hammerkit.yaml` and `.gitignore` are created (or updated) with the documented content.
-
-**Acceptance Scenarios**:
-
-1. **Given** an empty directory with no existing build file, **When** the user runs `hammerkit init`, **Then** a `.hammerkit.yaml` file is created containing an `envs: {}` block, a `tasks:` block with an `example` task using the `alpine` image and the command `echo "it's Hammer Time!"`.
-
-2. **Given** an empty directory with no existing `.gitignore`, **When** the user runs `hammerkit init`, **Then** a `.gitignore` file is created containing the entry `.hammerkit`.
-
-3. **Given** a directory that already has a `.gitignore`, **When** the user runs `hammerkit init`, **Then** the `.hammerkit` entry is appended to the existing `.gitignore` without overwriting other entries.
-
-4. **Given** a directory that already has a `.hammerkit.yaml`, **When** the user runs `hammerkit init`, **Then** the command succeeds (or warns) without overwriting the existing build file.
-
-### Edge Cases
-
-- If the user lacks write permissions in the working directory, `init` must exit with a non-zero code and a meaningful error message.
-- Running `init` when a `.hammerkit.yaml` already exists must not destroy existing configuration.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST create a `.hammerkit.yaml` file in the current working directory when `hammerkit init` is run and no build file exists.
-- **FR-002**: The generated `.hammerkit.yaml` MUST contain an `envs: {}` key and a `tasks:` key with at least one example task using the `alpine` image.
-- **FR-003**: System MUST create or update a `.gitignore` file in the current working directory to include the `.hammerkit` cache directory entry.
-- **FR-004**: System MUST print confirmation output indicating each file that was created or updated, including the file path.
-
-### Key Entities
-
-- **Build file (`.hammerkit.yaml`)**: The hammerkit project configuration file. Created by `init` with a minimal, runnable example task.
-- **Cache directory entry (`.hammerkit`)**: The directory hammerkit uses for local caching; excluded from version control via `.gitignore`.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: After `hammerkit init`, the file `.hammerkit.yaml` exists in the working directory and is parseable as valid YAML with the documented structure.
-- **SC-002**: After `hammerkit init`, the file `.gitignore` in the working directory contains the line `.hammerkit`.
-- **SC-003**: `hammerkit init` exits with code 0 and prints at least two confirmation lines (one per created/updated file).
-- **SC-004**: Running `hammerkit run example` immediately after `hammerkit init` in a Docker-enabled environment succeeds without manual editing.
-
-## Assumptions
-
-- `init` creates files relative to the current working directory (not a project-root detection heuristic).
-- The console confirmation output format is a checkmark prefix followed by the absolute path of each file, as shown in the docs example.
-- If `.hammerkit.yaml` already exists, `init` skips creation rather than overwriting; this is an informed guess based on the "non-destructive bootstrap" intent.
-- The `--file` global option does not affect where `init` writes the build file; it always writes `.hammerkit.yaml`.

package/specs/cli/ls/spec.md

@@ -1,66 +0,0 @@
-# Feature Specification: CLI: ls
-
-**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/ls.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Discovering available tasks and services (Priority: P1)
-
-A developer opens a project they are unfamiliar with and wants to understand what build tasks and services are defined before running anything. They run `hammerkit ls` and see a structured list of all services and tasks with their key attributes: ports, images, labels, source files, generated outputs, and inter-task dependencies.
-
-**Why this priority**: `ls` is the primary discovery and onboarding command; it must accurately reflect the build file content so users know what they can run.
-
-**Independent Test**: Given a build file containing at least one service and one task, run `hammerkit ls` and verify that both sections appear with correct attribute values.
-
-**Acceptance Scenarios**:
-
-1. **Given** a build file with a service `postgres` bound to port `5432` using image `postgres:12`, **When** the user runs `hammerkit ls`, **Then** the output contains a `Services:` section listing `postgres` with its port mapping (`127.0.0.1:5432 -> 5432`) and image.
-
-2. **Given** a build file with a task `install` that has an image, labels, src files, and generated outputs, **When** the user runs `hammerkit ls`, **Then** the output contains a `Tasks:` section listing `install` with all those attributes displayed.
-
-3. **Given** a build file with a task `api` that declares `needs: postgres` and `deps: install`, **When** the user runs `hammerkit ls`, **Then** the output for `api` shows both the `needs` (service dependency) and `deps` (task dependency) fields.
-
-4. **Given** a build file with only tasks and no services, **When** the user runs `hammerkit ls`, **Then** the output contains only a `Tasks:` section with no `Services:` section.
-
-### Edge Cases
-
-- A build file with no tasks and no services should produce empty or minimal output without crashing.
-- Labels with multiple key=value pairs must all appear on the same `labels:` line.
-- Tasks with multiple source files or generated outputs must list them space-separated.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST print a `Services:` section listing every service defined in the build file, each preceded by a bullet (`•`).
-- **FR-002**: For each service, system MUST display the port mappings and container image.
-- **FR-003**: System MUST print a `Tasks:` section listing every task defined in the build file, each preceded by a bullet (`•`).
-- **FR-004**: For each task, system MUST display the container image, labels (if any), source files (if any), generated outputs (if any), service dependencies via `needs:` (if any), and task dependencies via `deps:` (if any).
-- **FR-005**: System MUST omit attributes that are not set for a given task or service (no empty lines for unset fields).
-
-### Key Entities
-
-- **Service**: A long-running container dependency (e.g., a database) with port mappings and an image.
-- **Task**: A build step with an image, optional labels, source globs, generated paths, and optional dependencies on other tasks or services.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: `hammerkit ls` exits with code 0 for any valid build file.
-- **SC-002**: Every service and task name defined in the build file appears exactly once in the `hammerkit ls` output.
-- **SC-003**: Port mappings shown in the output match the bind address and container port declared in the build file.
-- **SC-004**: Label values shown in the output match the `key=value` pairs declared in the build file.
-
-## Assumptions
-
-- `ls` reads the default build file (`.hammerkit.yaml`) unless `--file` is supplied globally.
-- No filtering options are documented for `ls`; it always prints all services and all tasks.
-- The output format is plain text (not JSON or YAML) with a bullet-point layout as shown in the docs example.
-- The `Services:` section is printed before the `Tasks:` section when both are present.

package/specs/cli/package/spec.md

@@ -1,110 +0,0 @@
-# Feature Specification: CLI: package
-
-**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/package.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Build self-contained Docker images from container services (Priority: P1)
-
-A developer runs `hammerkit package <registry>` to turn every container service in their build file into a Docker image. Each image is named `<registry>/<service>:latest` and contains the service's base image plus the outputs generated by all of its dependency tasks, making the image runnable without hammerkit.
-
-**Why this priority**: This is the core purpose of the command — producing deployable, self-contained images from the build graph.
-
-**Independent Test**: Define a service with one dependency task that generates an output directory. Run `hammerkit package localhost:5000`. Confirm an image named `localhost:5000/<service>:latest` is created and that the generated directory is present inside the image.
-
-**Acceptance Scenarios**:
-
-1. **Given** a build file with a container service that has dependency tasks declaring `generates` outputs, **When** `hammerkit package <registry>` is run, **Then** a Docker image named `<registry>/<service>:latest` is produced with the dependency outputs baked in.
-
-2. **Given** a service with `envs`, `ports`, and `cmd` configured, **When** the image is built, **Then** the image encodes those values (environment variables, `EXPOSE` directives, and the default command) so the service runs correctly without hammerkit.
-
-3. **Given** a service with no dependency tasks, **When** `hammerkit package <registry>` is run, **Then** a valid image is still produced from the service's base image and any mounted sources.
-
-### User Story 2 - Push images to a container registry (Priority: P1)
-
-A CI pipeline operator adds `--push` to upload built images to a remote registry. Registry credentials are supplied via `-u`/`-p` flags. This enables promotion of a tested image across environments without rebuilding.
-
-**Why this priority**: Pushing to a registry is the primary delivery mechanism and is equally critical as building.
-
-**Independent Test**: Run `hammerkit package <registry> --push -u <user> -p <token>` and confirm the image is accessible in the registry under the expected name and tag.
-
-**Acceptance Scenarios**:
-
-1. **Given** `--push` is provided with valid `-u`/`-p` credentials, **When** `hammerkit package <registry> --push -u <u> -p <p>` completes, **Then** the image `<registry>/<service>:<tag>` is available in the remote registry.
-
-2. **Given** `--push` is omitted, **When** `hammerkit package <registry>` completes, **Then** the image is built locally only and not pushed.
-
-### User Story 3 - Pin an explicit image tag for release promotion (Priority: P2)
-
-A release engineer specifies `-t 1.2.3` so the produced image is tagged with a version number or a CI commit SHA rather than `latest`, enabling the same artifact to be promoted across staging and production.
-
-**Why this priority**: Reproducible, version-tagged images are required for safe promotion workflows.
-
-**Independent Test**: Run `hammerkit package <registry> -t 1.2.3` and confirm the resulting image tag is `<registry>/<service>:1.2.3`.
-
-**Acceptance Scenarios**:
-
-1. **Given** `-t 1.2.3` is supplied, **When** `hammerkit package <registry> -t 1.2.3` completes, **Then** the image is tagged `<registry>/<service>:1.2.3` instead of `latest`.
-
-### User Story 4 - Build for a specific target platform (Priority: P2)
-
-A developer on an Apple Silicon machine builds images targeting `linux/amd64` so the images can run on x64 production servers, by passing `--platform linux/amd64`.
-
-**Why this priority**: Cross-architecture builds are a common CI/CD requirement, especially in hybrid development environments.
-
-**Independent Test**: Run `hammerkit package <registry> --platform linux/amd64` on an arm64 host and confirm the produced image manifest declares the `linux/amd64` platform.
-
-**Acceptance Scenarios**:
-
-1. **Given** `--platform linux/amd64` is specified, **When** `hammerkit package <registry> --platform linux/amd64` is run on an arm64 host, **Then** the produced image targets the `linux/amd64` platform.
-
-2. **Given** `--platform` is omitted, **When** `hammerkit package <registry>` is run, **Then** the image targets the host architecture.
-
-### Edge Cases
-
-- Services without a container image (local-only services) are not packaged and are silently skipped.
-- Dependency tasks that run locally (without an `image` field) are not supported for packaging.
-- The `<registry>` argument is required; omitting it is an error.
-- `--push` without `-u`/`-p` relies on pre-authenticated Docker credentials (e.g., `docker login`); no error is thrown by hammerkit for missing flags if the daemon is already authenticated.
-- Cross-architecture builds require the Docker daemon to support the requested platform (buildkit/emulation); hammerkit forwards `--platform` to the Docker build and does not validate platform support independently.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST accept a required `<registry>` argument and produce a Docker image named `<registry>/<service>:<tag>` for every container service in the build file.
-- **FR-002**: System MUST generate a multi-stage Dockerfile per service that starts FROM the service's base image and copies in the `generates` outputs of all dependency tasks.
-- **FR-003**: System MUST apply the service's `envs`, `ports` (as `EXPOSE` directives), and `cmd` to the produced image.
-- **FR-004**: System MUST label each produced image with `hammerkit.dev/name` and `hammerkit.dev/id`.
-- **FR-005**: System MUST default the image tag to `latest` when `-t`/`--tag` is not specified.
-- **FR-006**: When `--push` is supplied, system MUST push the built image to the specified registry; credentials MAY be supplied via `-u`/`--username` and `-p`/`--password`.
-- **FR-007**: System MUST default to the host architecture when `--platform` is not specified, and MUST forward the specified platform to the Docker build when `--platform` is provided.
-- **FR-008**: System MUST support `-f`/`--filter` and `-e`/`--exclude` label options to limit which services are packaged.
-
-### Key Entities
-
-- **Container service**: A service defined in the build file with a base `image`; the unit of packaging.
-- **Registry**: The image-name prefix supplied by the user, used to construct the full image name `<registry>/<service>:<tag>`.
-- **Generated output**: Files or directories produced by a dependency task's `generates` field that are baked into the service image.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: After `hammerkit package <registry>`, a runnable Docker image exists locally for each container service, named `<registry>/<service>:<tag>`, containing all dependency task outputs.
-- **SC-002**: After `hammerkit package <registry> --push`, the image is accessible from the remote registry under the expected name and tag without any additional build steps.
-- **SC-003**: An image built with `hammerkit package <registry> -t <version>` carries exactly the tag `<version>` (not `latest`).
-- **SC-004**: An image built without hammerkit present in the runtime environment starts the service correctly using its declared `cmd`.
-
-## Assumptions
-
-- Packaging operates exclusively against the Docker runtime; non-Docker (local) services are out of scope.
-- The `--build-override-user` flag creates and runs a dedicated uid/gid 1000 user inside the image; its exact semantics beyond that are not specified in the doc and are not elaborated here.
-- The `<registry>` value is a plain string prefix with no validation by hammerkit; any registry format accepted by Docker is valid.
-- Services with no `deps` still produce a valid image from their base image and `mounts`; this is documented as supported behavior.

package/specs/cli/spec.md

@@ -1,73 +0,0 @@
-# Feature Specification: CLI: 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/cli/README.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Running hammerkit for the first time (Priority: P1)
-
-A developer downloads hammerkit and runs `hammerkit --help` to discover what commands are available. They see the full command list and global options, understand how to specify a custom build file, and know how to turn on verbose logging.
-
-**Why this priority**: The CLI entry point and help text are the first thing every user sees; a broken or incomplete help surface breaks all downstream workflows.
-
-**Independent Test**: Run `hammerkit --help` in a directory that contains a `.hammerkit.yaml` file and verify the output lists all commands and global options.
-
-**Acceptance Scenarios**:
-
-1. **Given** a directory with a valid `.hammerkit.yaml`, **When** the user runs `hammerkit --help`, **Then** the output includes the version flag (`-V, --version`), `--verbose`, `--file`, and all subcommands (`ls`, `clean`, `store`, `restore`, `package`, `validate`, `up`, `down`, `run`, `help`).
-
-2. **Given** any directory, **When** the user runs `hammerkit --version`, **Then** the current version number is printed.
-
-3. **Given** a directory with a valid build file, **When** the user runs `hammerkit --file custom.yaml <task>`, **Then** hammerkit uses `custom.yaml` as the build file instead of `.hammerkit.yaml`.
-
-4. **Given** a directory without a build file, **When** the user runs any command other than `init`, **Then** hammerkit reports that no build file is present and only the `init` command is available.
-
-### User Story 2 - Enabling verbose output (Priority: P2)
-
-A developer is troubleshooting an unexpected task result and wants to see internal debugging information. They add `--verbose` before the command and observe additional log lines.
-
-**Why this priority**: Debugging is a high-frequency need but not the primary happy path.
-
-**Independent Test**: Run `hammerkit --verbose ls` and confirm that extra debug-level log lines appear beyond what the default output produces.
-
-**Acceptance Scenarios**:
-
-1. **Given** a valid build file, **When** the user runs `hammerkit --verbose ls`, **Then** the output contains debugging information in addition to the normal task list.
-
-### Edge Cases
-
-- When no build file is found, hammerkit must restrict available commands to `init` only and surface a helpful message.
-- The `--file` flag accepts any path; if the file does not exist, hammerkit must report an error.
-- Global options (`--verbose`, `--file`) must be accepted before the subcommand name.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST provide a global `--verbose` flag that enables debug-level logging for any subcommand.
-- **FR-002**: System MUST provide a global `--file <path>` option that overrides the default build file path (`.hammerkit.yaml`).
-- **FR-003**: System MUST expose the following subcommands: `ls`, `clean`, `store`, `restore`, `package`, `validate`, `up`, `down`, `run`, `help`.
-- **FR-004**: System MUST treat `hammerkit <task>` (no explicit subcommand) as equivalent to `hammerkit run <task>` (default command).
-- **FR-005**: System MUST print the installed version when `--version` / `-V` is supplied.
-- **FR-006**: System MUST restrict available commands to `init` when no build file is present in the working directory.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: `hammerkit --help` exits with code 0 and lists all documented commands and global options.
-- **SC-002**: `hammerkit --version` exits with code 0 and prints a semantic version string.
-- **SC-003**: `hammerkit --file <nonexistent>` exits with a non-zero code and a human-readable error message.
-- **SC-004**: Running `hammerkit <task>` without the `run` keyword produces identical output to `hammerkit run <task>`.
-
-## Assumptions
-
-- The default build file name is `.hammerkit.yaml` (as shown in the CLI help output).
-- "Only `init` is available" when no build file is present means hammerkit exits with an error for all other commands, not that it silently ignores them.
-- `--verbose` applies globally to all subcommands; per-command verbosity overrides are not documented.

package/specs/cli/store-restore/spec.md

@@ -1,74 +0,0 @@
-# Feature Specification: CLI: store / restore
-
-**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/store-restore.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Cache CI artifacts between pipeline runs (Priority: P1)
-
-A developer configures their CI pipeline so that after each successful build, all task-generated outputs and the hammerkit cache are saved to a designated folder. On the next pipeline run, CI restores that folder first, then runs hammerkit. Tasks whose inputs have not changed are skipped because their outputs and cache state are already present, reducing total pipeline time.
-
-**Why this priority**: The primary value of store/restore is CI acceleration by avoiding redundant work across pipeline runs.
-
-**Independent Test**: Create a build file with a task that has `src` and `generates` fields. Run the task, store the cache, delete local outputs, restore the cache, and confirm hammerkit skips the task on the next run.
-
-**Acceptance Scenarios**:
-
-1. **Given** a build file with tasks that declare `generates` outputs, **When** `hammerkit store <dir>` is run after tasks have executed, **Then** all generated files/folders and the hammerkit cache are moved into `<dir>`.
-
-2. **Given** a previously stored cache directory `<dir>`, **When** `hammerkit restore <dir>` is run, **Then** the hammerkit cache and generated outputs are recovered so that unchanged tasks are skipped on the next run.
-
-3. **Given** a CI pipeline that saves and restores the cache directory between runs, **When** source inputs have not changed between runs, **Then** hammerkit skips the affected tasks on the second run.
-
-### User Story 2 - Selective state recovery after cache restoration (Priority: P2)
-
-A developer restores a previously stored cache and then modifies one source file. Only the task whose inputs changed is re-executed; all other tasks with unchanged inputs are still skipped.
-
-**Why this priority**: Demonstrates that store/restore integrates correctly with hammerkit's existing input-change detection rather than replacing it.
-
-**Independent Test**: After restoring a cache, modify one source file and run the dependent task. Confirm only that task executes and others are skipped.
-
-**Acceptance Scenarios**:
-
-1. **Given** a restored cache where some task outputs and cache state are present, **When** a source file for one task is modified and hammerkit is run, **Then** only the task whose source changed is re-executed.
-
-### Edge Cases
-
-- Running `hammerkit restore <dir>` when `<dir>` does not exist or is empty should not silently corrupt the local cache state.
-- Running `hammerkit store <dir>` when no tasks have generated any outputs should still complete without error.
-- The destination folder for `store` must be provided; omitting it is an error.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST accept a required destination folder argument for `hammerkit store <dir>` and move all task-generated outputs (declared via `generates`) and the hammerkit cache into that folder.
-- **FR-002**: System MUST accept a required source folder argument for `hammerkit restore <dir>` and recover the hammerkit cache and generated outputs from that folder into their expected locations.
-- **FR-003**: After a successful restore, hammerkit MUST recognize restored task outputs as valid cached results so that tasks with unchanged inputs are skipped on the next run.
-- **FR-004**: The store and restore commands MUST be designed for use in CI environments where the destination folder is managed by the CI caching mechanism.
-
-### Key Entities
-
-- **Cache directory**: A folder supplied by the user that holds the exported hammerkit cache state and all generated task outputs; it is the unit transferred between CI pipeline runs.
-- **Generated output**: A file or directory declared in a task's `generates` field that is produced by task execution and included in the stored cache.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A CI pipeline that uses store/restore completes a second run with unchanged inputs in less time than the first run, with task execution skipped for all tasks whose inputs have not changed.
-- **SC-002**: After `hammerkit store <dir>`, all directories and files listed in any task's `generates` field are present inside `<dir>`.
-- **SC-003**: After `hammerkit restore <dir>` followed by `hammerkit <task>`, the task execution log shows the task was skipped (cache hit) when inputs are unchanged.
-
-## Assumptions
-
-- The store command moves (rather than copies) generated outputs; the exact mechanism (move vs copy) is not critical to the observable contract but the doc says "moved".
-- Only container-compatible and local task outputs that appear in `generates` are included; tasks without a `generates` field contribute nothing to the store.
-- No `--filter`/`--exclude` options are documented for store/restore; the commands operate on all tasks in the build file.
-- The cache directory path is relative to the working directory unless an absolute path is given; this mirrors standard shell behavior.

package/specs/cli/up/spec.md

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